synthesisui 0.16.388 → 0.16.390

package/dist/claude-md.js

@@ -329,7 +329,7 @@ async function renderRegion(projectRoot, installed) {
             START,
             "## Design system",
             "",
-            "This project is wired to synthesisui and has **no design system yet** - so there is",
+            "This project has the synthesisui agent set up and **no design system yet** - so there is",
             "no token vocabulary to follow, and nothing here to obey.",
             "",
             "To turn this repository into one, run `/sui-import-ds` and I will read what is",

package/dist/commands/add.js

@@ -1,9 +1,9 @@
-import { access, mkdir, readdir, readFile, rm, writeFile, } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
-import { globalSheetOf, prefixFrom } from "../global-sheet.js";
+import { detectAppDirs, globalSheetOf, prefixFrom } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
 import { censusScope } from "../measured-scope.js";
@@ -131,57 +131,6 @@ async function readRootLock(path) {
     }
 }
 const exists = (path) => access(path).then(() => true, () => false);
-/**
- * ONDE AS ROTAS DELE MORAM DE VERDADE - e num monorepo elas não moram na raiz.
- *
- * Olhava só `app/` e `src/app/` na raiz. O `codelevel-monorepo` tem `apps/web/app` e
- * `apps/landing/app`, então a busca voltava null, o `appDir` caía no default `"app"`, e TODO caminho
- * impresso no setup apontava para uma pasta que não existe: `app/globals.css`, `app/layout.tsx`,
- * `app/fonts.ts`. O cliente lê três instruções e nenhuma serve para o repositório dele.
- *
- * O que faz uma pasta ser raiz de app é o `layout` do App Router morar dentro dela - por isso o
- * `apps/api` do Nest, que também é um workspace, não entra na lista.
- *
- * DEVOLVE TODAS, em ordem determinística: o setup é "once per app" e num monorepo isso é literal.
- * Escolher uma calada seria acertar uma e errar a outra sem dizer qual.
- */
-export async function detectAppDirs(root, pagesDir) {
-    const isAppRoot = async (dir) => {
-        if (!(await exists(join(root, dir))))
-            return false;
-        for (const ext of ["tsx", "jsx", "ts", "js"])
-            if (await exists(join(root, dir, `layout.${ext}`)))
-                return true;
-        return false;
-    };
-    const here = [pagesDir, `src/${pagesDir}`];
-    const nested = [];
-    for (const group of ["apps", "packages"]) {
-        let entries;
-        try {
-            entries = await readdir(join(root, group));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries.sort())
-            nested.push(`${group}/${entry}/${pagesDir}`, `${group}/${entry}/src/${pagesDir}`);
-    }
-    const found = [];
-    for (const dir of [...here, ...nested])
-        if (await isAppRoot(dir))
-            found.push(dir);
-    /**
-     * A RAIZ QUE EXISTE MAS NÃO TEM LAYOUT ainda é o melhor palpite de um app avulso - é o caso de um
-     * `create-next-app` no meio de uma migração. Sem isto, um projeto de app único perderia a detecção
-     * que já funcionava.
-     */
-    if (found.length === 0)
-        for (const dir of here)
-            if (await exists(join(root, dir)))
-                return [dir];
-    return found;
-}
 /**
  * Materializes a published DS into `_synthesisui/ds/<slug>/v<version>/`, points
  * stable root re-exports (tokens.css/theme.css) and a `.lock` at it, and updates

package/dist/commands/component.js

@@ -6,7 +6,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
-import { findCollision, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { findCollision, installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { inTheirTongue, projectTongue, sumSpoken, } from "../their-tongue.js";
@@ -149,11 +149,6 @@ export async function component(slug, name, opts) {
          * Re-materializing something WE generated is almost always what they meant, so
          * that keeps going. Shadowing a component of theirs stops and asks.
          */
-        const pascalName = res.name
-            .split(/[^a-zA-Z0-9]+/)
-            .filter(Boolean)
-            .map((p) => p[0].toUpperCase() + p.slice(1))
-            .join("");
         /**
          * THEY ALREADY HAVE THIS COMPONENT, and the recipe says where.
          *
@@ -316,7 +311,7 @@ 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);
+            local, await readInstalledScheme(root, slug), tongue, await installedThemeVars(root, slug));
             spoken = said;
             /**
              * AS DECLARAÇÕES DO ARQUIVO DELE QUE O INTERPRETADOR NÃO LEU - ver `unread-for-component.ts`.

package/dist/commands/doctor.js

@@ -17,12 +17,13 @@ import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from ".
 import { withTheirNames } from "../doctor/their-names.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
 import { FAMILY_SEAM_PREFIX } from "../fonts.js";
+import { detectAppDirs, globalSheetOf, prefixFrom } from "../global-sheet.js";
 import { groupRole } from "../group-role.js";
 import { actingSlug, describeScope, measuredScope, scopePaths, } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
+import { setupPrompt } from "../setup-prompt.js";
 import { resolveDeps } from "../stack.js";
 import { danglingTheirVars } from "../their-vars.js";
-import { wiringPrompt } from "../wiring-prompt.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -698,7 +699,9 @@ export async function doctor(opts) {
      * grupo está migrando para ela - e antes disto a referência existia na
      * plataforma e o comando que ordena a lista nunca ficava sabendo.
      */
-    const intent = intentOf(await readProjectConfig(root), opts.intent, groupRole(installed.groupLocks, installed.table.slug));
+    /** Lida uma vez: o `intent` ordena a lista e o setup abaixo deriva a folha e o nº de imports. */
+    const config = await readProjectConfig(root);
+    const intent = intentOf(config, opts.intent, groupRole(installed.groupLocks, installed.table.slug));
     const { recipes, documents } = installed;
     /**
      * A TABELA JÁ VEM COM O VOCABULÁRIO DELE DENTRO - ver `loadSystem` e `their-names.ts`.
@@ -961,7 +964,7 @@ export async function doctor(opts) {
         (!wiring.imported || !wiring.scoped || fontsPending);
     if (unwired) {
         console.log("");
-        console.log(body(`${table.name ?? table.slug} is installed - but not wired up yet.`));
+        console.log(body(`${table.name ?? table.slug} is installed - but this project does not load it yet.`));
         console.log("");
         console.log(body(wiring.imported
             ? `  ✓ some stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`
@@ -1005,19 +1008,50 @@ export async function doctor(opts) {
          * aqui já importou, materializou e rodou upgrade: mandá-lo ao `init` é devolver ao começo
          * alguém que está a um passo do fim.
          *
-         * E O PASSO JÁ EXISTIA PRONTO. `wiringPrompt` mora em `wiring-prompt.ts`, exportado, e era
+         * E O PASSO JÁ EXISTIA PRONTO. `setupPrompt` mora em `setup-prompt.ts`, exportado, e era
          * usado só pelo `init`. Imprimi-lo aqui não é texto novo: é a MESMA fonte chegando na tela
          * onde a pergunta nasce. Duas redações do mesmo passo divergiriam no primeiro conserto.
          *
-         * O PROMPT E NÃO O SNIPPET, porque o caminho do `@import` é relativo à folha global DELE e
-         * ninguém aqui sabe onde ela está. O prompt manda o agente rodar o doctor, ler o que ele
-         * nomeia e fazer - que é o que funciona em projeto arbitrário.
+         * O PROMPT LEVA A MEDIÇÃO, e até 07/09 ele era FIXO - o defeito que o dono leu na própria tela.
+         *
+         * As três linhas acima acabaram de imprimir `✗ ✓ ✓`: só o import faltava. O texto seguinte
+         * mandava *"Do the ONE-TIME SETUP it names, all of it"* e listava as três, então um agente
+         * obediente reescreve o escopo e o mapa de tipografia que já estavam corretos - contra a última
+         * linha do próprio texto, que pede para não mexer nos estilos dele. Um comando que mede e depois
+         * diz outra coisa gasta a medição.
+         *
+         * E A FOLHA TEM NOME, ao contrário do que este comentário dizia antes. `globalSheetOf` +
+         * `prefixFrom` são as mesmas funções que o `add` usa para achar a folha que os apps REALMENTE
+         * carregam - num monorepo não é o `globals.css` do app - e para contar o caminho relativo até a
+         * raiz. Elas existiam e este comando não as chamava; então ele descrevia o arquivo em vez de
+         * nomeá-lo, e o agente tinha que redescobrir o que a gente já sabia.
+         *
+         * Quando a derivação falha, `sheet` fica ausente e o texto volta a descrever - nenhum caminho é
+         * inventado.
          */
         if (table.slug) {
+            const appDirs = await detectAppDirs(root, config.pagesDir);
+            const sheet = appDirs[0]
+                ? await globalSheetOf(root, `${appDirs[0]}/globals.css`)
+                : null;
             console.log("");
-            console.log(body("Paste this into your agent - it does the wiring:"));
+            console.log(body("Paste this into your agent - it does the setup for you:"));
             console.log("");
-            console.log(snippet(wiringPrompt(table.slug).split("\n")));
+            console.log(snippet(setupPrompt(table.slug, {
+                tokens: !wiring.imported,
+                scope: !wiring.scoped,
+                /** Só é passo quando o projeto TEM o arquivo de fontes - ver `readWiring`. */
+                type: wiring.fontsWritten && !wiring.fontsMapped,
+                ...(sheet
+                    ? { sheet: { path: sheet, prefix: prefixFrom(sheet) } }
+                    : {}),
+                /**
+                 * DUAS LINHAS COM TAILWIND, UMA SEM - a mesma decisão que o `add` já toma pelo projeto.
+                 * Dizer "as duas linhas" a um projeto que precisa de uma manda o agente procurar o que
+                 * não existe.
+                 */
+                imports: config.styles === "css" ? 1 : 2,
+            }).split("\n")));
         }
     }
     /**

package/dist/commands/generate.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { installedSlugs } from "../installed.js";
-import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { postGenerate, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
@@ -75,7 +75,7 @@ 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 projectTongue(root, slug), await installedThemeVars(root, slug));
         for (const file of files) {
             await writeFile(join(compDir, file.filename), file.code, "utf8");
         }

package/dist/commands/init.js

@@ -1,8 +1,8 @@
 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 { wiringPrompt } from "../wiring-prompt.js";
 import { add } from "./add.js";
 /**
  * Bootstraps a project for SynthesisUI: writes `_synthesisui/config.json`
@@ -141,9 +141,9 @@ export async function init(opts) {
         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 wiring:"));
+        console.log(body("2. Open your agent and paste this once - it does the setup for you:"));
         console.log("");
-        console.log(snippet(wiringPrompt(opts.ds).split("\n")));
+        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."));

package/dist/commands/mcp.js

@@ -1286,7 +1286,7 @@ async function describeComponent(root, name) {
         const r = recipe.runtime;
         const lines = [];
         if (r.stateOwner === "caller") {
-            lines.push("State: the CALLER owns it - controlled only. Wire the pair below; do not add internal state.");
+            lines.push("State: the CALLER owns it - controlled only. Pass the pair below; do not add internal state.");
         }
         else if (r.stateOwner === "self") {
             lines.push("State: the component manages itself. Do not wire external state unless you need to read it.");

package/dist/commands/refit.js

@@ -4,7 +4,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { installedSlugs } from "../installed.js";
 import { body, section, snippet } from "../output.js";
-import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } 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 +121,7 @@ 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 projectTongue(root, slug), await installedThemeVars(root, slug));
         for (const f of files) {
             await writeFile(join(compDir, f.filename), f.code, "utf8");
         }

package/dist/commands/upgrade.js

@@ -8,7 +8,7 @@ import { unsentEvents } from "../doctor/ledger.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
 import { installedBehind, MATERIALISER_SINCE } from "../install-marks.js";
 import { body, section, snippet } from "../output.js";
-import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
+import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
@@ -331,6 +331,8 @@ 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);
         for (const entry of entries) {
             const tsxPath = join(componentsRoot, entry, `${entry}.tsx`);
             let head = "";
@@ -359,7 +361,7 @@ export async function upgrade(asked, opts) {
                 // Both were missing here, and `upgrade` is the command that REWRITES
                 // components somebody already has: without the convention it would have
                 // taken a working component and stripped its styles.
-                await reactMajorOf(root), res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug), tongue);
+                await reactMajorOf(root), res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug), tongue, themeVars);
                 /**
                  * A NOTA DAS DECLARAÇÕES NÃO INTERPRETADAS SOBREVIVE AO UPGRADE.
                  *

package/dist/commands/use.js

@@ -111,7 +111,7 @@ export async function use(slug, intent, opts) {
         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").',
-        "- Wire the behavior yourself (open/close, focus, routing) - the system ships the looks, not the JS.",
+        "- Implement the behavior yourself (open/close, focus, routing) - the system ships the looks, not the JS.",
         "",
         "Composition (make it look composed, not just correct):",
         config.target === "next"

package/dist/component-codegen.js

@@ -485,9 +485,31 @@ function remToTwScale(value) {
     const n = Number.parseFloat(m[1]) / 0.25;
     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.
+ *
+ * `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.
+ *
+ * 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]`.
+ *
+ * MEDIDO em 07/09 sobre TODOS os componentes das duas populações:
+ *
+ *     codelevel, repo real   58 de 110 utilitários de token (53%) não carregavam o valor dele
+ *     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.
+ */
+const minted = (themeVars, cssVar) => themeVars === null || themeVars.has(cssVar);
 /** One declaration → Tailwind classes (pretty when mappable, arbitrary-property
  *  otherwise - never dropped). */
-function declToTailwind(prop, value) {
+function declToTailwind(prop, value, themeVars) {
     const stat = STATIC[prop]?.[value];
     if (stat)
         return [stat];
@@ -496,19 +518,19 @@ function declToTailwind(prop, value) {
             if (value === "transparent")
                 return ["bg-transparent"];
             const key = colorKey(value);
-            if (key)
+            if (key && minted(themeVars, `--color-${key}`))
                 return [`bg-${key}`];
             break;
         }
         case "color": {
             const key = colorKey(value);
-            if (key)
+            if (key && minted(themeVars, `--color-${key}`))
                 return [`text-${key}`];
             break;
         }
         case "borderColor": {
             const key = colorKey(value);
-            if (key)
+            if (key && minted(themeVars, `--color-${key}`))
                 return [`border-${key}`];
             break;
         }
@@ -517,25 +539,28 @@ function declToTailwind(prop, value) {
             const m = value.match(/^1px\s+solid\s+(\{[^}]+\})$/);
             if (m) {
                 const key = colorKey(m[1]);
-                if (key)
+                if (key && minted(themeVars, `--color-${key}`))
                     return ["border", `border-${key}`];
             }
             break;
         }
         case "borderRadius": {
             const key = nsKey(value, "radius");
-            if (key)
+            if (key && minted(themeVars, `--radius-${key}`))
                 return [`rounded-${key}`];
             break;
         }
         case "gap": {
             const key = nsKey(value, "spacing");
-            if (key)
+            if (key && minted(themeVars, `--spacing-${key}`))
                 return [`gap-${key}`];
             break;
         }
         case "padding": {
-            const keys = value.split(/\s+/).map((v) => nsKey(v, "spacing"));
+            const keys = value
+                .split(/\s+/)
+                .map((v) => nsKey(v, "spacing"))
+                .map((k) => (k && minted(themeVars, `--spacing-${k}`) ? k : null));
             if (keys.length === 1 && keys[0])
                 return [`p-${keys[0]}`];
             if (keys.length === 2 && keys[0] && keys[1])
@@ -544,25 +569,25 @@ function declToTailwind(prop, value) {
         }
         case "fontSize": {
             const key = scaleKey(value);
-            if (key)
+            if (key && minted(themeVars, `--text-${key}`))
                 return [`text-${key}`];
             break;
         }
         case "fontFamily": {
             const key = nsKey(value, "typography.families");
-            if (key)
+            if (key && minted(themeVars, `--font-${key}`))
                 return [`font-${key}`];
             break;
         }
         case "fontWeight": {
             const key = nsKey(value, "typography.weights");
-            if (key)
+            if (key && minted(themeVars, `--font-weight-${key}`))
                 return [`font-${key}`];
             break;
         }
         case "boxShadow": {
             const key = nsKey(value, "shadow");
-            if (key)
+            if (key && minted(themeVars, `--shadow-${key}`))
                 return [`shadow-${key}`];
             break;
         }
@@ -648,8 +673,8 @@ function twStateVariants(state) {
     const native = TW_NATIVE.has(word) ? [`${word}:`] : [`data-[${word}]:`];
     return [...native, ...(TW_ALSO[state] ?? [])];
 }
-function blockToTailwind(block, prefix = "") {
-    return Object.entries(block).flatMap(([prop, value]) => declToTailwind(prop, value).map((cls) => `${prefix}${cls}`));
+function blockToTailwind(block, themeVars, prefix = "") {
+    return Object.entries(block).flatMap(([prop, value]) => declToTailwind(prop, value, themeVars).map((cls) => `${prefix}${cls}`));
 }
 /** Every prefix combination one layer needs. A condition that cannot be
  *  expressed returns no combination, and the layer is dropped rather than
@@ -773,23 +798,25 @@ function resolveNode(node, scheme, asRoot) {
     return { variants, states, conditional };
 }
 /** The classes every compound condition contributes, in layer order. */
-const conditionalClasses = (resolved) => resolved.conditional.flatMap((c) => blockToTailwind(c.style, c.prefix));
+const conditionalClasses = (resolved, themeVars) => resolved.conditional.flatMap((c) => blockToTailwind(c.style, themeVars, c.prefix));
 function tailwindClassList(recipe, 
 /** The node's states and compound conditions, already read off its layers. */
 resolved, 
+/** O que a folha instalada declara - ver `minted`. */
+themeVars, 
 /** CSS properties a variant axis owns - see `variantOwnedProps`. */
 exclude) {
     const base = exclude
         ? Object.fromEntries(Object.entries(recipe.base).filter(([prop]) => !exclude.has(prop)))
         : recipe.base;
     const classes = [
-        ...blockToTailwind(base),
+        ...blockToTailwind(base, themeVars),
         // States keep everything: `hover:` and `disabled:` cannot collide with an
         // unprefixed variant class, so there is nothing to resolve.
-        ...Object.entries(resolved.states).flatMap(([state, block]) => twStateVariants(state).flatMap((prefix) => blockToTailwind(block, prefix))),
+        ...Object.entries(resolved.states).flatMap(([state, block]) => twStateVariants(state).flatMap((prefix) => blockToTailwind(block, themeVars, prefix))),
         // Compound conditions last: they are the most specific thing the recipe says,
         // and in utilities the later class is the one a reader expects to win.
-        ...conditionalClasses(resolved),
+        ...conditionalClasses(resolved, themeVars),
     ];
     return classes.join(" ");
 }
@@ -1160,7 +1187,14 @@ function emitTailwindMode(slug, name, recipe, version, props,
 /** The name it takes in THEIR project. The utilities stay the system's. */
 localName = name, 
 /** The scheme the document opens in - see `generateComponentFiles`. */
-scheme = "dark") {
+scheme = "dark", 
+/**
+ * O QUE A FOLHA INSTALADA DECLARA - ver `minted`, e é o que decide de quem é o VALOR.
+ *
+ * `null` mantém o comportamento de sempre: um projeto sem `add` não tem folha nenhuma, e ali o
+ * nome legível não custa nada porque nada pinta de qualquer forma.
+ */
+themeVars = null) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
     const axes = rootAxes(recipe);
@@ -1170,13 +1204,13 @@ scheme = "dark") {
         .filter((a) => !a.boolean)
         .map((a) => {
         const entries = a.options
-            .map((o) => `  ${JSON.stringify(o)}: ${JSON.stringify(blockToTailwind(resolved.variants[a.key]?.[o] ?? {}).join(" "))},`)
+            .map((o) => `  ${JSON.stringify(o)}: ${JSON.stringify(blockToTailwind(resolved.variants[a.key]?.[o] ?? {}, themeVars).join(" "))},`)
             .join("\n");
         return `const ${a.prop.toUpperCase()}: Record<string, string> = {\n${entries}\n};`;
     });
     const booleanConsts = axes
         .filter((a) => a.boolean)
-        .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(resolved.variants[a.key]?.true ?? {}).join(" "))};`);
+        .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(resolved.variants[a.key]?.true ?? {}, themeVars).join(" "))};`);
     // Every property some axis controls leaves BASE, and the base value becomes
     // that axis's default - so exactly one class ever sets it and the prop
     // actually wins.
@@ -1206,7 +1240,7 @@ scheme = "dark") {
         const fromDefault = preset
             ? (resolved.variants[a.key]?.[preset] ?? {})
             : {};
-        return JSON.stringify(blockToTailwind({ ...fromBase, ...fromDefault }).join(" "));
+        return JSON.stringify(blockToTailwind({ ...fromBase, ...fromDefault }, themeVars).join(" "));
     };
     const clsParts = [
         "BASE",
@@ -1251,7 +1285,7 @@ ${dataAttrLines(axes)}${axes.length ? "\n" : ""}    `;
 import type { ${needsElementType ? `ElementType, ${props}` : props} } from "react";
 import { cn } from "../cn";
 
-const BASE = ${JSON.stringify([needsGroup ? "group" : "", tailwindClassList(recipe, resolved, excluded)].filter(Boolean).join(" "))};
+const BASE = ${JSON.stringify([needsGroup ? "group" : "", tailwindClassList(recipe, resolved, themeVars, excluded)].filter(Boolean).join(" "))};
 ${[...variantConsts, ...booleanConsts].join("\n")}
 
 type ${comp}Props = ${propsType(axes, tag, props, el.offersAs)};
@@ -1302,9 +1336,9 @@ ${orderedParts
          * status colours of his card were still nowhere.
          */
         const partResolved = resolveNode(part, scheme, false);
-        const partVariantClasses = partAxes.flatMap((a) => a.options.flatMap((o) => blockToTailwind(partResolved.variants[a.key]?.[o] ?? {}, `data-[${a.attr}=${o}]:`)));
+        const partVariantClasses = partAxes.flatMap((a) => a.options.flatMap((o) => blockToTailwind(partResolved.variants[a.key]?.[o] ?? {}, themeVars, `data-[${a.attr}=${o}]:`)));
         const partCls = [
-            tailwindClassList(part, partResolved),
+            tailwindClassList(part, partResolved, themeVars),
             ...partVariantClasses,
         ]
             .filter(Boolean)
@@ -1398,7 +1432,16 @@ scheme,
  * Aqui a tradução acontece uma vez, sobre os bytes que vão a disco, e `tsc` recusa a meia-chamada
  * de um materializador novo - o mesmo argumento do `scheme` logo acima.
  */
-tongue) {
+tongue, 
+/**
+ * O QUE A FOLHA INSTALADA DECLARA NO `@theme` - `installedThemeVars(root, slug)`.
+ *
+ * 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
+ * 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.
+ */
+themeVars) {
     const files = [];
     const props = propsTypeName(reactMajor);
     if (styles === "css") {
@@ -1411,7 +1454,7 @@ tongue) {
     else {
         files.push({
             filename: `${localName}.tsx`,
-            code: `${emitTailwindMode(slug, name, recipe, version, props, localName, scheme)}\n`,
+            code: `${emitTailwindMode(slug, name, recipe, version, props, localName, scheme, themeVars)}\n`,
         });
     }
     files.push({

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

@@ -104,5 +104,5 @@ register("pt-BR", {
     "the import, orchestrated": "o import, orquestrado",
     "one component against the system": "um componente contra o sistema",
     "build what the system does not have": "construir o que o sistema não tem",
-    "the tokens, wired into your app": "os tokens, ligados no seu app",
+    "the tokens, loaded by your app": "os tokens, carregados pelo seu app",
 });

package/dist/global-sheet.js

@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { dirname, join, posix, relative, resolve } from "node:path";
+import { exists } from "./agent-wiring.js";
 /**
  * A FOLHA GLOBAL QUE OS APPS DELE REALMENTE CARREGAM - e num monorepo ela quase nunca é a do app.
  *
@@ -101,3 +102,51 @@ export function prefixFrom(sheet) {
     const up = relative(dirname(resolve("/r", sheet)), "/r");
     return up === "" ? "./" : `${up.split(/[\\/]/).join("/")}/`;
 }
+/**
+ * A RAIZ DE CADA APP DESTE REPOSITÓRIO - onde o escopo e a tipografia entram, um por app.
+ *
+ * MORA AQUI E NÃO NO `add` (07/09): o `doctor` precisa desta resposta para nomear a folha no texto
+ * que ele entrega, e importá-la de `commands/add.ts` puxou a rede para dentro de um comando local -
+ * `INV-COLETA-05` reprovou, e com razão. A pergunta *"quais pastas deste repositório são app?"* é
+ * leitura de disco e não tem nada a ver com publicar nem buscar: ela pertence ao módulo da folha.
+ *
+ * O que faz uma pasta ser app é o `layout` do App Router morar dentro dela. Um workspace sem
+ * `layout` (uma API, um pacote de config) não é app e não recebe escopo.
+ */
+export async function detectAppDirs(root, pagesDir) {
+    const isAppRoot = async (dir) => {
+        if (!(await exists(join(root, dir))))
+            return false;
+        for (const ext of ["tsx", "jsx", "ts", "js"])
+            if (await exists(join(root, dir, `layout.${ext}`)))
+                return true;
+        return false;
+    };
+    const here = [pagesDir, `src/${pagesDir}`];
+    const nested = [];
+    for (const group of ["apps", "packages"]) {
+        let entries;
+        try {
+            entries = await readdir(join(root, group));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort())
+            nested.push(`${group}/${entry}/${pagesDir}`, `${group}/${entry}/src/${pagesDir}`);
+    }
+    const found = [];
+    for (const dir of [...here, ...nested])
+        if (await isAppRoot(dir))
+            found.push(dir);
+    /**
+     * A RAIZ QUE EXISTE MAS NÃO TEM LAYOUT ainda é o melhor palpite de um app avulso - é o caso de um
+     * `create-next-app` no meio de uma migração. Sem isto, um projeto de app único perderia a detecção
+     * que já funcionava.
+     */
+    if (found.length === 0)
+        for (const dir of here)
+            if (await exists(join(root, dir)))
+                return [dir];
+    return found;
+}

package/dist/install-marks.js

@@ -170,7 +170,7 @@
  * O que o cliente ganha ao rodar `upgrade`: o agente dele no Codex passa a poder PERGUNTAR ao
  * sistema, em vez de só receber as regras e adivinhar o resto.
  */
-export const MATERIALISER_SINCE = "0.16.388";
+export const MATERIALISER_SINCE = "0.16.390";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/project-facts.js

@@ -171,3 +171,43 @@ export async function readInstalledScheme(root, slug) {
         return "dark";
     }
 }
+/**
+ * O QUE A FOLHA INSTALADA DECLARA NO `@theme` - a resposta que decide de quem é o VALOR.
+ *
+ * O QUE O CLIENTE PERCEBE SEM ISTO: o componente sai vestindo `rounded-lg` e `font-mono`, a classe
+ * existe em qualquer projeto com Tailwind, e ela pinta o **default do Tailwind** em vez do raio e da
+ * fonte do sistema dele. Nada falta na tela - é a mesma peça com os números de outra biblioteca, o
+ * que é mais difícil de achar que uma classe morta.
+ *
+ * A folha deixa de declarar por dois motivos legítimos: o alinhamento tirou a linha para não roubar
+ * uma classe que o app dele já usa (`INV-VOLTA-13`), ou o compilador não faz ponte para um nome que
+ * não está em `meta.ownedNames`. Os dois se leem no mesmo lugar - o arquivo que caiu na pasta dele -
+ * e é por isso que a pergunta é respondida AQUI e não no servidor: só nesta máquina existe a folha
+ * que ele realmente tem.
+ *
+ * MEDIDO em 07/09 sobre todos os componentes: 58 de 110 utilitários de token no `codelevel` (53%) e
+ * 34 de 241 no `ember` (14%) não carregavam o valor do sistema.
+ *
+ * `null` quando não há folha - projeto sem `add`, ou install antigo. Nesse caso nada pinta de
+ * qualquer forma, e o `refit`/`generate` já dizem isso.
+ */
+export async function installedThemeVars(root, slug) {
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const version = await pinnedVersion(dir);
+    if (!version)
+        return null;
+    const css = await readFile(join(dir, `v${version}`, "theme.css"), "utf8").catch(() => "");
+    if (!css)
+        return null;
+    /**
+     * Só o que está DENTRO de um `@theme` conta - é a única coisa que o Tailwind v4 lê para gerar
+     * utilitário. Uma variável no `[data-ds]` do `tokens.css` não gera nada, e foi tratar as duas como
+     * iguais que fez o `theme.css` parecer suficiente quando não era.
+     */
+    const blocks = css.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g);
+    const declared = new Set();
+    for (const block of blocks)
+        for (const m of block[1].matchAll(/^\s*(--[a-zA-Z0-9-]+)\s*:/gm))
+            declared.add(m[1]);
+    return declared;
+}

package/dist/setup-prompt.js

@@ -0,0 +1,95 @@
+/**
+ * O TEXTO QUE TIRA AS EDIÇÕES DE SETUP DA MÃO DA PESSOA - e que agora USA a medição.
+ *
+ * O QUE O CLIENTE GANHA: um design system instalado não muda um pixel até que alguma folha que o app
+ * carrega importe os tokens e algum elemento carregue o escopo. Em 27/07 isso foi medido em 0% - a
+ * lista numerada de três passos existia e ninguém a executava. A pessoa que roda o comando tem um
+ * agente aberto ao lado, então o fecho deixou de ser tarefa e passou a ser um texto para colar.
+ *
+ * O DEFEITO QUE ISTO CORRIGE (dono, 07/09): o texto era FIXO. O `doctor` acabava de imprimir
+ * `✗ ✓ ✓` - só o import faltava, o escopo e a tipografia já estavam lá - e o parágrafo seguinte
+ * mandava *"Do the ONE-TIME SETUP it names, all of it"*, listando as três. Um agente obediente
+ * reescreve o que já estava correto, e o próprio texto termina com "não mexa nos meus estilos": ele
+ * se contradizia dentro de si mesmo.
+ *
+ * Então o que falta é ARGUMENTO. Sem ele o texto pede tudo, que é a verdade nos dois lugares onde
+ * ninguém mediu nada: o fecho do `init` (o projeto acabou de receber o sistema) e a tela do
+ * onboarding (a plataforma não vê o disco de ninguém). Com ele, o texto pede o que falta e NOMEIA o
+ * que já está pronto para o agente deixar em paz.
+ *
+ * GÊMEO POR SPEC com `apps/web/src/lib/ds/install-mission.ts`, que serve o mesmo texto na tela -
+ * `setup-prompt.spec.ts` reprova o drift. O CLI é publicado standalone e não pode importar de
+ * `apps/web`, então a cópia é inevitável; o que não é inevitável é ela divergir em silêncio, e dois
+ * textos diferentes para o mesmo setup ensinam dois setups.
+ */
+export function initCommand(slug) {
+    return `npx synthesisui@latest init --styles tailwind --ds ${slug}`;
+}
+/**
+ * A LINHA QUE DÁ SAÍDA QUANDO UMA VERSÃO ESTÁ PROPAGANDO (dono, 07/09).
+ *
+ * Ele rodou `npx synthesisui@latest doctor` e recebeu `ETARGET / No matching version found`: o
+ * `dist-tag` do npm já apontava para a versão nova e o tarball ainda não estava na réplica que a
+ * máquina dele consultou. O erro é do npm e acontece ANTES do nosso código rodar, então não há como
+ * interceptá-lo - o que está na nossa mão é a instrução não deixar quem lê sem saída, porque
+ * `ETARGET` não diz que é transitório nem o que fazer.
+ */
+const PROPAGATING = "If npm answers `ETARGET` or `No matching version found`, a release is still propagating - wait a minute and run it again, or pin the version the registry does have (`npm view synthesisui version`).";
+const CONNECT_STEP = `Run: npx synthesisui@latest connect
+   ${PROPAGATING}
+   If it answers "already had it" on both lines, everything is live and you are done.
+   If it WROTE either of them, then they are not live in this session, because hooks and tools are only read at startup. Stop there and tell me, in bold, on its own line: **RESTART THIS SESSION - the check is installed but not running yet.** Do not keep writing files after that; a session that cannot be checked is the state this whole setup exists to avoid.`;
+/** As linhas exatas quando a folha é conhecida; a descrição do arquivo quando não é. */
+function importStep(slug, gap) {
+    const lines = [
+        `@import "${gap.sheet ? gap.sheet.prefix : "<path to the repo root>/"}_synthesisui/ds/${slug}/tokens.css";`,
+        ...(gap.imports === 2
+            ? [
+                `@import "${gap.sheet ? gap.sheet.prefix : "<path to the repo root>/"}_synthesisui/ds/${slug}/theme.css";`,
+            ]
+            : []),
+    ];
+    const where = gap.sheet
+        ? `\`${gap.sheet.path}\``
+        : "the global stylesheet this project's apps actually load (in a monorepo that is usually the shared package's, not the app's)";
+    return `Add ${gap.imports === 2 ? "these two lines" : "this line"} to ${where}, RIGHT AFTER its \`@import "tailwindcss"\` line:
+
+${lines.map((l) => `      ${l}`).join("\n")}
+
+   The position is not cosmetic. Read there, this sheet comes BEFORE any \`@theme\` this project declares, so wherever both name the same variable the project's own value wins. Moved to the end of the file, ours would win instead - silently.`;
+}
+export function setupPrompt(slug, gap) {
+    const g = gap ?? {
+        tokens: true,
+        scope: true,
+        type: true,
+        imports: 2,
+    };
+    const done = [
+        g.tokens ? null : "a stylesheet already imports the system's tokens",
+        g.scope ? null : `\`data-ds="${slug}"\` is already on a root element`,
+        g.type
+            ? null
+            : "this project's type is already mapped onto the system's family tokens",
+    ].filter(Boolean);
+    const steps = [];
+    if (g.tokens)
+        steps.push(importStep(slug, g));
+    if (g.scope)
+        steps.push(`Put \`data-ds="${slug}"\` on a root element of each app - the element every page renders inside. Keep any classes it already has; a background they chose is a decision they made.`);
+    if (g.type)
+        steps.push(`Map this project's type onto the system's family tokens: import from the fonts file the install wrote and point the family variables at it, in the same stylesheet. This is the step people skip, and without it the pages render in the framework's default face.`);
+    steps.push(`Run: npx synthesisui@latest doctor
+   ${PROPAGATING}
+   If it says "no system installed", the install never happened - run \`${initCommand(slug)}\` and then start over from step 1.
+   It must NOT say "this project does not load it yet". If it does, it names exactly which piece is still missing - fix that one and run it again.`);
+    steps.push(CONNECT_STEP);
+    const alreadyDone = done.length > 0
+        ? `\nAlready in place - LEAVE THESE ALONE:\n${done.map((d) => `- ${d}`).join("\n")}\n`
+        : "";
+    return `Set up the "${slug}" design system in this project, so its tokens reach the browser. I already ran the install in my terminal.
+${alreadyDone}
+${steps.map((s, i) => `${i + 1}. ${s}`).join("\n")}
+
+Do not change any of my existing styles.`;
+}

package/dist/skill-configure.js

@@ -10,4 +10,4 @@
  * e essa era a única parte da instalação que ninguém escrevia, só imprimia.
  */
 export const CONFIGURE_SKILL_PATH = ".claude/skills/sui-configure-ds/SKILL.md";
-export const CONFIGURE_SKILL = '---\nname: sui-configure-ds\ndescription: Wire an installed design system into the app so its tokens actually reach the browser - the stylesheet import, the data-ds scope, and the type. Use when a system is installed and the app does not look themed, when `doctor` reports "installed - but not wired up yet", or when somebody asks to set up / connect / configure the design system in their app ("configura o design system aqui", "why aren\'t the tokens working", "/sui-configure-ds"). Asks the doctor first and does nothing when the three checks already pass.\n---\n\n# Wiring the system into the app - served live\n\nThis playbook is served from the platform, not shipped in this file - it is\nalways current, and your context only carries the step you are on.\n\n1. Call the `playbook` tool on the `synthesisui` MCP server with\n   { "skill": "configure" } - you get the framing and a table of contents.\n2. Fetch ONLY the chapter for the step you are on:\n   { "skill": "configure", "section": "<id from the toc>" }. Never fetch more\n   than the current step needs.\n3. Follow it exactly. When the step is done, fetch the next chapter.\n\nStart by running `npx synthesisui doctor`: the three lines it prints are what\ndecide the work, and three ticks means there is nothing to do.\n\nIf the tool answers that you are not signed in, run `npx synthesisui login`\nin the terminal and call it again. If the `synthesisui` MCP server is not\navailable at all, run `npx synthesisui connect`, restart the session, and\ninvoke this skill again.\n';
+export const CONFIGURE_SKILL = '---\nname: sui-configure-ds\ndescription: Set up an installed design system in the app so its tokens actually reach the browser - the stylesheet import, the data-ds scope, and the type. Use when a system is installed and the app does not look themed, when `doctor` reports "installed - but this project does not load it yet", or when somebody asks to set up / connect / configure the design system in their app ("configura o design system aqui", "why aren\'t the tokens working", "/sui-configure-ds"). Asks the doctor first and does nothing when the three checks already pass.\n---\n\n# Setting the system up in the app - served live\n\nThis playbook is served from the platform, not shipped in this file - it is\nalways current, and your context only carries the step you are on.\n\n1. Call the `playbook` tool on the `synthesisui` MCP server with\n   { "skill": "configure" } - you get the framing and a table of contents.\n2. Fetch ONLY the chapter for the step you are on:\n   { "skill": "configure", "section": "<id from the toc>" }. Never fetch more\n   than the current step needs.\n3. Follow it exactly. When the step is done, fetch the next chapter.\n\nStart by running `npx synthesisui doctor`: the three lines it prints are what\ndecide the work, and three ticks means there is nothing to do.\n\nIf the tool answers that you are not signed in, run `npx synthesisui login`\nin the terminal and call it again. If the `synthesisui` MCP server is not\navailable at all, run `npx synthesisui connect`, restart the session, and\ninvoke this skill again.\n';

package/dist/skills.js

@@ -67,6 +67,6 @@ export const SKILLS = [
         path: CONFIGURE_SKILL_PATH,
         source: CONFIGURE_SKILL,
         label: "/sui-configure-ds",
-        what: "the tokens, wired into your app",
+        what: "the tokens, loaded by your app",
     },
 ];

package/package.json

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

package/dist/wiring-prompt.js

@@ -1,34 +0,0 @@
-/**
- * O PASTE QUE TIRA AS QUATRO EDIÇÕES DA MÃO DA PESSOA.
- *
- * `init --ds` termina imprimindo uma seção "One-time setup" com três passos
- * numerados para o humano fazer à mão: os dois `@import`, o `data-ds` na raiz
- * e a fiação das fontes. Foi exatamente aí que 27/07 mediu 0% de fiação -
- * ninguém fazia, e o sistema que acabara de chegar não aparecia na tela.
- *
- * A pessoa que roda esse comando tem um agente aberto ao lado. Então o fecho
- * deixa de ser uma lista de tarefas e passa a ser uma coisa para colar.
- *
- * GÊMEO POR SPEC com `apps/web/src/lib/ds/install-mission.ts`, que serve o
- * mesmo texto na tela do onboarding - `wiring-prompt.spec.ts` reprova o drift.
- * O CLI é publicado standalone e não pode importar de `apps/web`, então a
- * cópia é inevitável; o que não é inevitável é ela divergir em silêncio, e um
- * prompt que diverge entre a tela e o terminal ensina duas fiações diferentes
- * para o mesmo sistema.
- */
-export function initCommand(slug) {
-    return `npx synthesisui@latest init --styles tailwind --ds ${slug}`;
-}
-export function wiringPrompt(slug) {
-    return `Wire the "${slug}" design system into this project. I already ran the install in my terminal.
-
-1. Run: npx synthesisui@latest doctor
-   If it says "no system installed", I skipped the install - run ${initCommand(slug)} first, then carry on.
-2. Do the ONE-TIME SETUP it names, all of it: the two @import lines in the project's global stylesheet (the path is relative to that file), data-ds="${slug}" on the root element, and the font wiring - importing from the fonts file it writes and mapping those variables in the stylesheet. The type is the step people skip.
-3. Run doctor again. It must NOT say "not wired up yet". If it does, it names exactly which piece is missing - fix that and run it again.
-4. Run: npx synthesisui@latest connect
-   If it answers "already had it" on both lines, everything is live and you are done.
-   If it WROTE either of them, then they are not live in this session, because hooks and tools are only read at startup. Stop there and tell me, in bold, on its own line: **RESTART THIS SESSION - the check is installed but not running yet.** Do not keep writing files after that; a session that cannot be checked is the state this whole setup exists to avoid.
-
-Do not change any of my existing styles.`;
-}