synthesisui 0.16.421 → 0.16.423

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

@@ -8,6 +8,7 @@ import { markSent, readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { sampledForUpload } from "../doctor/style-ledger.js";
 import { describeDelta, fingerprintReadings, readSyncMark, writeSyncMark, } from "../last-sync.js";
+import { installedVersion, landedLine, localEdits, readInstalledPair, sentLine, settleBaseline, } from "../local-edits.js";
 import { measuredScope, rememberScope } from "../measured-scope.js";
 import { fromCensus } from "../memory/observation.js";
 import { reportMeasurement } from "../memory/report.js";
@@ -551,6 +552,43 @@ export async function remeasure(args) {
             return;
         }
     }
+    /**
+     * O QUE ELE MUDOU NO DESIGN SYSTEM INSTALADO, lido do disco e sem rede.
+     *
+     * A comparação é contra `.installed.json`, a cópia que o `add` deixa ao lado. Um sistema
+     * instalado antes desta etapa não a tem, e aí o comando DIZ o que falta em vez de tratar o
+     * documento inteiro como mudado - ver `readInstalledPair`.
+     */
+    let edits = [];
+    let localDocument = null;
+    let localSaid = null;
+    {
+        const version = await installedVersion(root, slug);
+        /**
+         * UM ERRO INESPERADO AQUI É DITO, e não engolido. A primeira escrita caía em
+         * "not-installed" para qualquer exceção - um disco cheio, uma permissão, um link quebrado -
+         * e a saída ficava idêntica à de um repositório sem sistema instalado.
+         */
+        const pair = version
+            ? await readInstalledPair(root, slug, version).catch((error) => ({
+                kind: "unreadable",
+                where: `_synthesisui/ds/${slug}/v${version}`,
+                why: error instanceof Error ? error.message : String(error),
+            }))
+            : { kind: "not-installed" };
+        if (pair.kind === "pair") {
+            edits = localEdits(pair.installed, pair.local);
+            if (edits.length > 0)
+                localDocument = pair.local;
+            localSaid = sentLine(edits, slug);
+        }
+        else if (pair.kind === "unreadable") {
+            localSaid = `your local ${slug} could not be read, so nothing of it went up: ${pair.why}\n      ${pair.where}`;
+        }
+        else if (pair.kind === "no-baseline") {
+            localSaid = `we cannot tell what changed in your local ${slug}: ${pair.why}`;
+        }
+    }
     const res = await fetch(`${base}/api/registry/ds/${slug}/census`, {
         method: "POST",
         headers: {
@@ -568,6 +606,17 @@ export async function remeasure(args) {
             census: census.ledger
                 ? { ...census, ledger: sampledForUpload(census.ledger) }
                 : census,
+            /**
+             * E O QUE O AGENTE DELE MUDOU NOS ARQUIVOS DO DESIGN SYSTEM - a outra metade do ciclo.
+             *
+             * O prompt que a plataforma monta termina mandando rodar este comando, e até aqui ele
+             * media só o CÓDIGO dele: o design system instalado aparecia apenas para descobrir quais
+             * slugs existem. O documento só sobe quando há diferença de verdade contra o que o `add`
+             * instalou - sem edição, este campo não existe e nada muda do lado de lá.
+             */
+            ...(edits.length > 0 && localDocument
+                ? { document: localDocument, edits }
+                : {}),
         }),
     }).catch(() => null);
     if (!res?.ok) {
@@ -580,6 +629,20 @@ export async function remeasure(args) {
     console.log("");
     console.log(section("Sent"));
     console.log(body(`${out.written ?? 0} of ${out.total ?? 0} components written.`));
+    /**
+     * O QUE VEIO DOS ARQUIVOS DELE, DITO - e antes de qualquer outra nota, porque é a única parte
+     * desta saída que fala do trabalho que ELE acabou de fazer.
+     *
+     * Um "ok" mudo depois de um agente ter mexido em doze peças é pior que nenhuma saída: ele não
+     * tem como saber se o comando entendeu o trabalho, e roda de novo para conferir.
+     */
+    if (localSaid)
+        console.log(body(localSaid));
+    /** A única frase no passado, e ela vem DEPOIS da resposta do servidor. */
+    if (out.hisEdits?.applied)
+        console.log(body(landedLine(out.hisEdits.applied, slug)));
+    if (out.hisEdits?.refused)
+        console.log(body(paint.strong(`  ✕ your local changes were refused, and nothing of them was written: ${out.hisEdits.refused}`)));
     for (const note of out.notes ?? [])
         console.log(body(paint.faint(note)));
     /**
@@ -662,6 +725,27 @@ export async function remeasure(args) {
         ...(args.cli ? { cli: args.cli } : {}),
         readings: fingerprintReadings(census.components),
     };
+    /**
+     * E O BASELINE PASSA A SER O QUE ESTÁ NO DISCO - a metade que fecha o ciclo.
+     *
+     * Sem esta linha, todo `sync` reenviaria a mesma alteração para sempre, e o documento na
+     * plataforma ganharia uma revisão nova a cada rodada sem nada ter mudado. Só depois de o
+     * servidor ter aceitado: uma recusa mantém o baseline velho, para a próxima rodada tentar de
+     * novo em vez de esquecer o que ele fez.
+     */
+    /**
+     * A CONDIÇÃO É `applied`, e não "não recusou" - a diferença apaga o trabalho dele.
+     *
+     * Um servidor que responde 200 SEM o campo `hisEdits` é todo deploy anterior a esta etapa, e
+     * essa janela existe de verdade: o CLI é publicado antes de a plataforma subir. Com
+     * `!refused`, o CLI dava o baseline por assentado, o disco esquecia o que o agente fez, e a
+     * plataforma nunca tinha recebido. A alteração some dos dois lados.
+     */
+    if (out.hisEdits?.applied && localDocument) {
+        const version = await installedVersion(root, slug);
+        if (version)
+            await settleBaseline(root, slug, version, localDocument).catch(() => { });
+    }
     console.log(body(paint.faint(describeDelta(mark, await readSyncMark(root)))));
     await writeSyncMark(root, mark);
     /**

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):",