synthesisui 0.16.421 → 0.16.422

package/dist/commands/generate.js

@@ -2,8 +2,9 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { detectAppDirs } from "../global-sheet.js";
 import { installedSlugs } from "../installed.js";
-import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { reactMajorOf, readInstalledConvention, readInstalledScheme, theirThemeVars, } from "../project-facts.js";
 import { postGenerate, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
@@ -75,7 +76,17 @@ export async function generate(description, opts) {
         // project as the stylesheet it has to match.
         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));
+        await projectTongue(root, slug), 
+        /**
+         * 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)));
         /**
          * A EDICAO DELE VENCE A REESCRITA (T7) - a leitura que faltava.
          *
@@ -109,8 +120,18 @@ export async function generate(description, opts) {
         console.log(`  • <${comp} /> - compose its parts + content (see the recipe)`);
     }
     else {
-        console.log(`  • @import "_synthesisui/ds/${slug}/generated/${res.name}.css" in your CSS`);
-        console.log(`  • <div data-ds="${slug}"><div class="ds-${res.name}">…</div></div>`);
+        /**
+         * O ARQUIVO NÃO É IMPORTADO DA NOSSA PASTA - `INV-GERAL-13`, 11/09.
+         *
+         * A instrução mandava `@import "_synthesisui/ds/<slug>/generated/<name>.css"` e envolver a
+         * marcação num `data-ds` nosso. As duas apontavam para dentro da nossa pasta, e é a dependência
+         * que esta etapa fechou.
+         *
+         * A folha gerada já passou pela porta de tradução, então ela fala o vocabulário dele: copiá-la
+         * para onde as folhas dele vivem não perde nada, e o que fica aqui segue sendo a referência.
+         */
+        console.log(`  • copy _synthesisui/ds/${slug}/generated/${res.name}.css next to your own stylesheets - it already speaks your vocabulary, and nothing of ours has to be loaded`);
+        console.log(`  • <div class="ds-${res.name}">…</div>`);
     }
     console.log(`  (${res.usage.inputTokens} in / ${res.usage.outputTokens} out tokens · AI action - additive; nothing else changed)`);
 }

package/dist/commands/import.js

@@ -4643,7 +4643,7 @@ export async function runImport(opts) {
      */
     if (payload?.slug) {
         /**
-         * A FIAÇÃO DELE CONTRA O SLUG QUE NASCEU - e este aviso sai do CLI, não da skill.
+         * O QUE O CSS DELE AINDA IMPORTA - e este aviso sai do CLI, não da skill.
          *
          * MEDIDO em 24/08: o `globals.css` dele importa `_synthesisui/ds/codelevel/`, o nome escolhido
          * derivou `codelevel-ds`, ninguém mencionou, e o `next build` dele terminou em exit code 1 com
@@ -4658,7 +4658,7 @@ export async function runImport(opts) {
         const warning = wiringWarning(census.wiredSlugs ?? [], payload.slug);
         if (warning) {
             console.log("");
-            console.log(section("Your CSS points somewhere else"));
+            console.log(section("Your CSS still imports a stylesheet of ours"));
             for (const line of warning.split("\n"))
                 console.log(body(line));
         }

package/dist/commands/init.js

@@ -1,6 +1,5 @@
 import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
 import { body, section, snippet } from "../output.js";
-import { setupPrompt } from "../setup-prompt.js";
 import { resolveDeps, stylesFor, tailwindMajor } from "../stack.js";
 import { formMix, measuredStyle } from "../styles-flavour.js";
 import { add } from "./add.js";
@@ -134,19 +133,23 @@ export async function init(opts) {
             dir: root,
             setupHints: false,
         });
+        /**
+         * ERAM DOIS PASSOS E É UM - `INV-GERAL-13`, 11/09.
+         *
+         * O passo 2 colava `setupPrompt` no agente dele: dois `@import` da nossa folha, um `data-ds` na
+         * árvore dele, e o mapa de tipografia. Ele não existe mais, porque nada que a plataforma escreve
+         * precisa de folha nossa carregada - e um comando de primeira vez é o pior lugar possível para
+         * ensinar uma dependência que o produto promete não criar.
+         */
         console.log("");
-        console.log(section("Two steps left, and neither is a file you edit"));
-        console.log(body("1. Turn the check and the tools on - run this BEFORE you open your agent,"));
-        console.log(body("   because hooks and tools are read when a session starts:"));
+        console.log(section("One step left, and it is not a file you edit"));
+        console.log(body("Turn the check and the tools on - run this BEFORE you open your agent,"));
+        console.log(body("because hooks and tools are read when a session starts:"));
         console.log("");
         console.log(snippet(["npx synthesisui@latest connect"]));
         console.log("");
-        console.log(body("2. Open your agent and paste this once - it does the setup for you:"));
-        console.log("");
-        console.log(snippet(setupPrompt(opts.ds).split("\n")));
-        console.log("");
-        console.log(body("Then ask it for something real. The check introduces itself on the first"));
-        console.log(body("clean file and goes quiet after that."));
+        console.log(body("Then ask your agent for something real. The check introduces itself on the"));
+        console.log(body("first clean file and goes quiet after that."));
         return;
     }
     console.log("");

package/dist/commands/refit.js

@@ -2,9 +2,10 @@ import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { detectAppDirs } from "../global-sheet.js";
 import { installedSlugs } from "../installed.js";
 import { body, section, snippet } from "../output.js";
-import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { reactMajorOf, readInstalledConvention, readInstalledScheme, theirThemeVars, } from "../project-facts.js";
 import { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
@@ -121,7 +122,17 @@ export async function refit(file, opts) {
         const flavourOf = await flavourResolver(root, config.styles);
         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));
+        await projectTongue(root, slug), 
+        /**
+         * 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)));
         /**
          * A EDICAO DELE VENCE A REESCRITA (T7) - a leitura que faltava, a mesma do `generate`.
          *

package/dist/commands/summary.js

@@ -68,12 +68,16 @@ export async function summary(slug, opts) {
     /**
      * LINHA 3 - O QUE FAZER AGORA, e é uma coisa só.
      *
-     * As duas linhas de fiação são o portão de tudo o mais: sem elas nenhum token chega ao navegador e
-     * todo número seguinte é vazio. O `doctor` diz isso melhor e com o estado real, então o próximo passo
-     * é ele - não uma explicação nossa aqui.
+     * AS DUAS LINHAS DE FIAÇÃO SAÍRAM EM 11/09 - `INV-GERAL-13`. Elas eram descritas aqui como *"o
+     * portão de tudo o mais"*, e essa frase era verdadeira enquanto o que a plataforma escrevia
+     * dependia da nossa folha. Não depende mais: um componente chega falando os nomes que o código
+     * dele declara, ou carregando o valor.
+     *
+     * Este é o último ecrã da primeira corrida, e é o pior lugar do produto para ensinar uma
+     * dependência - ele é lido uma vez, com atenção, por alguém que está decidindo se fica.
      */
     console.log("");
-    console.log(body("Two lines wire it up, and `init` printed both:"));
-    console.log(body(paint.dim(`  @import "./_synthesisui/ds/${slug}/tokens.css";   and   data-ds="${slug}" on <html>`)));
+    console.log(body("Nothing of ours goes into your code - there is no"));
+    console.log(body("stylesheet to import and no attribute to add."));
     console.log(paint.blue(snippet(["npx synthesisui@latest doctor"])));
 }

package/dist/commands/template.js

@@ -1,11 +1,18 @@
 import { mkdir, writeFile } from "node:fs/promises";
 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 { installedSheetCss, RECIPE_HEADER, recipeRulesFor, } from "../recipe-css.js";
+import { fetchDesignSystem, fetchTemplate } from "../registry.js";
+import { inTheirTongue, projectTongue, tongueFromArtifacts, } from "../their-tongue.js";
 import { keptLine, recordWritten, editedHere as theirEdits, } from "../written.js";
 /**
+ * A INSTRUÇÃO SAI DE TODA PÁGINA, SEMPRE - `INV-GERAL-13`, 11/09.
+ *
+ * Esta filtragem era CONDICIONAL: ela rodava só quando a medição dizia que a página não precisava
+ * mais da folha, e no caso contrário o comentário ficava no arquivo dele mandando importar. Não há
+ * mais caso contrário - as regras que a página veste são copiadas para o `.css` ao lado dela
+ * (`recipe-css.ts`), e nada no arquivo aponta para nós.
+ *
  * 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
@@ -88,12 +95,28 @@ export async function template(slug, name, opts) {
         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
-     * falava a língua dele; a promessa é uma só. Sem mapa no `.lock`, nada é traduzido e a folha
-     * instalada continua sendo o caminho - e a saída diz qual dos dois aconteceu.
+     * NENHUMA MATERIALIZAÇÃO VAZA VOCABULÁRIO INTERNO (INV-VOLTA-02) - a mesma porta do `component`,
+     * e agora também o mesmo CAMINHO DE LEITURA.
+     *
+     * SEM `add`, O SISTEMA VEM DO REGISTRY. Uma página trazida antes do install - e o próprio guard
+     * de edição deste comando já reconhece esse fluxo - não tinha pasta para ler, `projectTongue`
+     * respondia `null`, e o arquivo ia a disco com `var(--ds-*)` cru e as classes `.ds-*` sem uma
+     * regra sequer. Calado: o relatório da tradução só existe quando houve tradução.
+     *
+     * O `component` recebeu este conserto em 10/09 (`tongueFromArtifacts`) e o `template` não - "a
+     * mesma promessa, duas implementações, uma delas ausente" é literalmente o defeito que
+     * `INV-VOLTA-02` nomeia, e ele estava aqui.
+     *
+     * UMA IDA A MAIS À REDE, e só neste caminho: quem já instalou lê do disco como sempre.
      */
-    const tongue = await projectTongue(root, slug);
+    const installedTongue = await projectTongue(root, slug);
+    const fromRegistry = installedTongue
+        ? null
+        : await fetchDesignSystem(base, slug, opts.version).catch(() => null);
+    const tongue = installedTongue ??
+        (fromRegistry
+            ? await tongueFromArtifacts(root, fromRegistry.artifacts)
+            : null);
     const speak = (code) => (tongue ? inTheirTongue(code, tongue) : null);
     let named = 0;
     let inlined = 0;
@@ -130,38 +153,55 @@ export async function template(slug, name, opts) {
             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.
+     * AS REGRAS DE RECEITA VÊM JUNTO, no `.css` ao lado da página - `INV-GERAL-13`, 11/09.
      *
-     * 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.
+     * O QUE MUDOU PARA O CLIENTE: a página renderiza sem nada nosso carregado no app dele. Ela veste
+     * `.ds-hero`, `.ds-nav` e as outras classes que o sistema declara, e essas regras passam a morar
+     * no arquivo ao lado dela - traduzidas para o vocabulário dele, como todo o resto.
      *
-     * 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.
+     * POR QUE A PÁGINA ERA O ÚLTIMO CASO. Ela é a única materialização que dependia da folha por
+     * CLASSE, e não por variável: a tradução reescreve `var(--ds-*)` e não tem o que fazer com
+     * `.ds-hero`, porque o corpo daquela regra nunca esteve no arquivo. Enquanto isso fosse verdade,
+     * este comando terminava mandando instalar o sistema e colar um `@import` - e foi essa instrução
+     * que abriu esta etapa.
      *
-     * 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.
+     * O CSS COPIADO PASSA PELA MESMA PORTA: `translate` é a tradução que todo byte deste comando
+     * atravessa, e um caminho que escreve CSS sem passá-la é o defeito que `INV-VOLTA-02` nomeia.
      */
-    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;
+    const recipes = recipeRulesFor({
+        source: pieces.map((f) => f.content).join("\n"),
+        /**
+         * A FOLHA DE ONDE AS REGRAS SÃO COPIADAS - do disco quando ele instalou, do registry quando não.
+         *
+         * Sem as duas, `recipes.rules` é 0 e a página sai vestindo `.ds-*` que ninguém declara - com o
+         * cabeçalho dela afirmando que a folha ao lado escopa cada regra. Uma frase falsa dentro do
+         * arquivo dele é pior que uma instrução: o terminal rola, o arquivo fica.
+         */
+        sheetCss: fromRegistry?.artifacts?.["tokens.css"] ??
+            (await installedSheetCss(root, slug)),
+    });
+    if (recipes.rules > 0) {
+        /**
+         * O ARQUIVO IRMÃO É O DESTINO, e ele já existe no alvo `next` - a página o importa desde que
+         * as media queries e o hambúrguer CSS-only passaram a viajar nele. Criar um terceiro arquivo
+         * daria à página dois CSS para importar e a ninguém uma razão.
+         */
+        const sibling = pieces.find((p) => p.filename.endsWith(".css"));
+        const block = `${RECIPE_HEADER}\n${translate(recipes.css)}\n`;
+        if (sibling)
+            sibling.content = `${block}\n${sibling.content}`;
+        else
+            pieces.push({
+                rel: join(dirname(pageRel), pageFile.filename.replace(/\.tsx$/, ".css")),
+                filename: pageFile.filename.replace(/\.tsx$/, ".css"),
+                content: block,
+            });
+    }
     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);
+        const content = withoutTheSheetInstruction(piece.content);
         await writeFile(join(root, piece.rel), content, "utf8");
         landed.push({ filename: piece.filename, content });
         console.log(piece.rel === pageRel
@@ -180,35 +220,23 @@ export async function template(slug, name, opts) {
         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) {
             const sample = [...still].sort().slice(0, 3).join(", ");
-            console.log(`  ${still.size} still point${still.size === 1 ? "s" : ""} at our stylesheet (${sample}${still.size > 3 ? ", …" : ""}), so tokens.css is still needed here.`);
+            console.log(`  ${still.size} value${still.size === 1 ? "" : "s"} the system declares no value for (${sample}${still.size > 3 ? ", …" : ""}) - ${still.size === 1 ? "that declaration is" : "those declarations are"} dropped by the browser. Please report this: the sheet we read is incomplete.`);
         }
     }
+    if (recipes.rules > 0)
+        console.log(`  ${recipes.rules} rule${recipes.rules === 1 ? "" : "s"} for ${recipes.classes.slice(0, 3).join(", ")}${recipes.classes.length > 3 ? `, +${recipes.classes.length - 3}` : ""} came along in the stylesheet next to it - nothing to import.`);
     console.log("");
     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$/, "")}";`);
-    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(`  • nothing to install: this page and its stylesheet stand on their own`);
     console.log("  • refine the file: wire real data, split into components, swap placeholders");
     /**
-     * E A LINHA DO ESCOPO SÓ SAI ONDE ELA É VERDADE - medido rodando o comando em 10/09.
+     * E A LINHA DO ESCOPO NÃO SAI MAIS - `INV-GERAL-13`, 11/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.
+     * Ela mandava *"keep the data-ds wrapper and the ds-* classes (stays on-system)"*. O `data-ds`
+     * existia para a NOSSA folha aplicar dentro dele, e o app dele não a carrega: pedir que ele
+     * mantenha um atributo nosso na árvore dele é a mesma dependência com outro nome. As classes
+     * continuam valendo, e agora elas são declaradas pelo arquivo ao lado da própria página.
      */
-    if (chargesTheSheet)
-        console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
 }

package/dist/commands/upgrade.js

@@ -7,9 +7,10 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
+import { detectAppDirs } from "../global-sheet.js";
 import { installedBehind, MATERIALISER_SINCE } from "../install-marks.js";
 import { body, section, snippet } from "../output.js";
-import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { reactMajorOf, readInstalledConvention, readInstalledScheme, theirThemeVars, } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
@@ -419,8 +420,9 @@ export async function upgrade(asked, opts) {
          * língua do repositório. Resolvido uma vez para a corrida inteira, como o sabor.
          */
         const tongue = await projectTongue(root, slug);
-        /** A folha instalada é a MESMA para a corrida inteira - ver `installedThemeVars`. */
-        const themeVars = await installedThemeVars(root, slug);
+        /** O `@theme` DELE é o MESMO para a corrida inteira - ver `theirThemeVars`. */
+        /** As pastas de app - a resposta é a INTERSEÇÃO delas. Ver `theirThemeVars`. */
+        const themeVars = await theirThemeVars(root, await detectAppDirs(root, config.pagesDir));
         for (const entry of entries) {
             const tsxPath = join(componentsRoot, entry, `${entry}.tsx`);
             let head = "";

package/dist/commands/use.js

@@ -90,10 +90,12 @@ export async function use(slug, intent, opts) {
     // The styling contract differs by target: Next projects in this product use
     // Tailwind v4 backed by the DS; the "general" target is framework-agnostic CSS.
     const stylingRule = config.target === "general"
-        ? `- Style with the design system only: reuse the \`.ds-*\` recipe classes and the ` +
-            `\`var(--ds-*)\` custom properties. Never use raw hex/px outside the system's scale.`
-        : `- Style with the design system only: reuse the \`.ds-*\` recipe classes and the ` +
-            `DS-backed Tailwind utilities (${utilities}…). Never use raw hex/px outside the system's scale.`;
+        ? `- Style with the design system only: bring its recipes in as code ` +
+            `(\`npx synthesisui component ${slug} <name>\`) and write the names THIS project declares - ` +
+            `\`find_token\` answers with the exact one. Never use raw hex/px outside the system's scale.`
+        : `- Style with the design system only: bring its recipes in as code ` +
+            `(\`npx synthesisui component ${slug} <name>\`) and use this project's own Tailwind utilities ` +
+            `(${utilities}…). Never use raw hex/px outside the system's scale.`;
     const task = intent.trim() || "build the UI I describe next";
     const prompt = [
         `Use the "${name}" design system (slug: ${slug}, v${version}) to: ${task}`,
@@ -106,11 +108,8 @@ export async function use(slug, intent, opts) {
             `\`${config.componentsDir}/\` and \`${config.pagesDir}/\`). If it does, modify only what's ` +
             `needed and keep the rest of the file intact and on-system. If it doesn't, build it new - ` +
             `components in \`${config.componentsDir}/\`, pages in \`${config.pagesDir}/\`.`,
-        `- Scope the markup with \`data-ds="${slug}"\` (or rely on it at the app root).`,
         stylingRule,
-        config.target === "next"
-            ? '- Make sure `tokens.css` + `theme.css` are imported in the global CSS (see the GUIDE\'s "How to apply").'
-            : '- Make sure `tokens.css` is imported in the global CSS (see the GUIDE\'s "How to apply").',
+        "- Nothing of the platform's is imported into this project: a component brought in by `component` carries everything it needs.",
         "- Implement the behavior yourself (open/close, focus, routing) - the system ships the looks, not the JS.",
         "",
         "Composition (make it look composed, not just correct):",

package/dist/component-codegen.js

@@ -470,8 +470,16 @@ const scaleKey = (v) => {
     const m = v.match(/^\{typography\.scale\.([a-zA-Z0-9-]+)\.fontSize\}$/);
     return m ? kebab(m[1]) : null;
 };
-/** "{color.semantic.primary}" → "var(--ds-color-semantic-primary)" - the raw
- *  scoped vars always exist, so arbitrary-property fallbacks never dangle. */
+/**
+ * "{color.semantic.primary}" → "var(--ds-color-semantic-primary)" - a grafia INTERNA, que a porta
+ * de tradução (`speak`) reescreve no nome dele ou no valor literal antes de qualquer byte ir a
+ * disco.
+ *
+ * ELA NUNCA SOBREVIVE ATÉ O ARQUIVO DELE (`INV-GERAL-13`): `speak` é a última coisa que roda em
+ * `generateComponentFiles`, e `nothing-of-ours-is-asked-for.spec.ts` reprova o texto que sair daqui
+ * com a nossa grafia dentro. Existe como forma intermediária porque é ela que carrega o caminho da
+ * referência (`color.semantic.primary`) até a folha que sabe o valor.
+ */
 const refToDsVar = (v) => v.replace(/\{([a-z0-9.-]+)\}/gi, (_, path) => {
     return `var(--ds-${path.split(".").map(kebab).join("-")})`;
 });
@@ -531,25 +539,28 @@ function remToTwScale(value) {
     return Number.isInteger(n) && n >= 0 && n <= 96 ? String(n) : null;
 }
 /**
- * O UTILITÁRIO NOMEADO SÓ VALE QUANDO A FOLHA INSTALADA O DECLARA - e é isso que decide o VALOR.
+ * O UTILITÁRIO NOMEADO SÓ VALE QUANDO O `@theme` **DELE** O DECLARA - e é isso que decide o VALOR.
  *
  * `rounded-lg` existe em qualquer projeto com Tailwind, então a classe nunca "falta". O que muda é
- * de quem é o valor: quando o `theme.css` que caiu na pasta dele declara `--radius-lg`, a classe
- * pinta o raio DO SISTEMA; quando não declara, ela pinta o default do Tailwind - e o componente
- * mente em silêncio, que é pior que uma classe morta, porque nada na tela parece faltar.
+ * de quem é o valor: quando o `@theme` do projeto dele declara `--radius-lg`, a classe pinta o raio
+ * DELE, e a decisão continua sendo dele; quando não declara, ela pinta o default do Tailwind - e o
+ * componente mente em silêncio, que é pior que uma classe morta, porque nada na tela parece faltar.
  *
- * A folha não declara por dois motivos, os dois legítimos: a redefinição roubaria uma classe que o
- * app dele já usa (`INV-VOLTA-13`, o alinhamento), ou o compilador não faz ponte para um nome que
- * não está em `meta.ownedNames` (o `--font-body` do codelevel). Nos dois casos a resposta certa é a
- * mesma: emitir o valor arbitrário com `var(--ds-*)`, que resolve sempre dentro de `[data-ds]`.
+ * A PERGUNTA ERA SOBRE A NOSSA FOLHA ATÉ 11/09, e era a última dependência de runtime que o código
+ * entregue carregava. `rounded-lg` escrito porque o NOSSO `theme.css` declara `--radius-lg` só pinta
+ * o sistema num app que importa aquele arquivo - e `INV-GERAL-13` diz que nenhum app dele importa. O
+ * componente saía com a aparência certa na nossa cabeça e o raio do Tailwind na tela dele.
  *
- * MEDIDO em 07/09 sobre TODOS os componentes das duas populações:
+ * QUANDO ELE NÃO DECLARA, a resposta é o valor arbitrário - e a porta de tradução o resolve no nome
+ * dele ou no literal, nunca numa variável nossa.
  *
- *     codelevel, repo real   58 de 110 utilitários de token (53%) não carregavam o valor dele
+ * MEDIDO em 07/09 sobre TODOS os componentes das duas populações, com a folha NOSSA respondendo:
+ *
+ *     codelevel, repo real   58 de 110 utilitários de token (53%) já caíam no arbitrário
  *     ember, app novo        34 de 241 (14%)
  *
- * `null` é projeto sem folha instalada - `refit` e `generate` já dizem que nada pinta sem o `add`,
- * e ali o nome legível não custa nada.
+ * `null` é "ninguém mediu" - `refit` e `generate` já dizem que nada pinta sem o `add`, e ali o nome
+ * legível não custa nada.
  */
 const minted = (themeVars, cssVar) => themeVars === null || themeVars.has(cssVar);
 /** One declaration → Tailwind classes (pretty when mappable, arbitrary-property
@@ -890,15 +901,27 @@ function variantOwnedProps(variants, axis) {
     return [...props];
 }
 // ── Emission ─────────────────────────────────────────────────────────────────
+/**
+ * O CABEÇALHO DO ARQUIVO DELE - e as duas linhas de setup saíram dele em 11/09.
+ *
+ * O QUE ELAS DIZIAM, dentro de TODO `.tsx` que a plataforma escreve no repositório dele:
+ * *"Global setup (once per app): import _synthesisui/ds/<slug>/tokens.css"* e *"put data-ds=<slug>
+ * on a root element"*. Era a instrução que o produto promete não dar, escrita no lugar onde ela
+ * sobrevive a qualquer conserto do terminal - e ela ficava lá, num arquivo dele, para todo agente
+ * e toda pessoa lerem depois (`INV-GERAL-13`).
+ *
+ * E ELA FAZIA UM SEGUNDO ESTRAGO, medido em 10/09: `readWiring` procurava essas mesmas strings no
+ * repositório para responder *"este projeto carrega o sistema?"*, então a partir do primeiro
+ * componente que NÓS escrevemos ela respondia `imported: true` sobre um projeto que não importa
+ * nada. Um comentário nosso nunca provou nada sobre o projeto dele.
+ *
+ * O que fica é a PROCEDÊNCIA - quem escreveu, de qual sistema, em que versão. Ela não pede nada; ela
+ * responde a pergunta de quem abre o arquivo daqui a seis meses.
+ */
 function header(slug, name, version, mode) {
-    const setup = mode === "tailwind"
-        ? `import _synthesisui/ds/${slug}/theme.css (Tailwind adapter) + tokens.css`
-        : `import _synthesisui/ds/${slug}/tokens.css`;
     return [
         `// Generated by SynthesisUI - "${name}" from the "${slug}" design system (v${version}).`,
-        `// On-system by construction: every style resolves to the DS tokens.`,
-        `// Global setup (once per app): ${setup}`,
-        `// and put data-ds="${slug}" on a root element (e.g. <body data-ds="${slug}">).`,
+        `// Every value here is a name YOUR code declares, or the value itself - nothing to import.`,
         ...(mode === "tailwind" ? [OVERRIDE_WARNING] : []),
     ].join("\n");
 }
@@ -1507,12 +1530,16 @@ scheme,
  */
 tongue, 
 /**
- * O QUE A FOLHA INSTALADA DECLARA NO `@theme` - `installedThemeVars(root, slug)`.
+ * O QUE O `@theme` **DELE** DECLARA - `theirThemeVars(root)`.
  *
  * OBRIGATÓRIO, pelo mesmo argumento do `scheme` e do `tongue`: o utilitário nomeado que este
- * módulo escreve só carrega o valor DO SISTEMA quando a folha que caiu na pasta dele declara a
+ * módulo escreve só carrega um valor de design quando o `@theme` do PROJETO dele declara a
  * variável. Sem essa resposta o codegen escreve `rounded-lg` e a classe pinta o default do
- * Tailwind - o componente mente sem nada faltar na tela. `null` é projeto sem folha instalada.
+ * Tailwind - o componente mente sem nada faltar na tela.
+ *
+ * ERA A NOSSA FOLHA QUE RESPONDIA ISTO, e essa era a última dependência de runtime que o código
+ * entregue ainda tinha (`INV-GERAL-13`, 11/09). `null` é "ninguém mediu", e continua significando
+ * que o nome legível não custa nada - `refit` e `generate` já dizem que nada pinta sem o `add`.
  */
 themeVars) {
     const files = [];

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

@@ -66,6 +66,9 @@ register("pt-BR", {
     "already current": "já está em dia",
     "updated to this CLI's pipeline": "atualizada para esta versão",
     "removed - renamed to /sui-import-ds": "removida - virou /sui-import-ds",
+    /** A skill aposentada fica no repositório dele, nomeada - ver `RETIRED_SKILLS`. */
+    "retired - nothing of ours loads in your app any more": "aposentada - nada nosso carrega no seu app",
+    "it stays in your repo - yours to delete": "ela fica no seu repositório - sua para apagar",
     // ── onde o bloco de regras caiu ──
     "how to turn this repo into your system": "como transformar este repo no seu sistema",
     "rewritten for what is installed": "reescrito para o que está instalado",

package/dist/doctor/apply-fix.js

@@ -437,7 +437,7 @@ export function describeFix(result, dry) {
     const lines = [];
     if (applied.length === 0) {
         lines.push(decisions > 0
-            ? `Nothing to apply. All ${decisions} findings are values your system has no name for - those are design decisions, not fixes.`
+            ? `Nothing to apply. All ${decisions} findings are values your own code names nowhere - those are design decisions, not fixes. Name one and \`--fix\` picks it up.`
             : relative > 0
                 ? `Nothing to apply. All ${relative} findings are lengths in \`em\`, which follow the element's font size - swapping them can move the layout, so that call is yours.`
                 : /**
@@ -531,6 +531,6 @@ export function describeFix(result, dry) {
     const rewritten = new Set(applied.map((a) => `${a.file}:${a.line}`));
     const halfWritten = skipped.filter((s) => rewritten.has(`${s.file}:${s.line}`)).length;
     if (halfWritten > 0)
-        lines.push(`  ${halfWritten} of those ${halfWritten === 1 ? "sits" : "sit"} on a line this command just rewrote - a shorthand comes back with a token and a literal side by side (\`padding: 8px var(--ds-spacing-24)\`). See them by value: npx synthesisui doctor --migrate`);
+        lines.push(`  ${halfWritten} of those ${halfWritten === 1 ? "sits" : "sit"} on a line this command just rewrote - a shorthand comes back with a token and a literal side by side (\`padding: 8px var(--spacing-24)\`). See them by value: npx synthesisui doctor --migrate`);
     return lines;
 }