synthesisui 0.16.389 → 0.16.394

package/dist/absorb-plan.js

@@ -10,7 +10,11 @@ const HOME = {
 };
 /** Uma palavra de categoria no começo do nome deles não é família - é a categoria repetida. */
 const CATEGORY = /^(color|colour|radius|rounded|spacing|space|gap|font|type|text|duration|motion|ease|easing)-/;
-const clean = (name) => name.replace(/^--/, "").toLowerCase();
+/**
+ * O nome sem o sigilo. `$` e `@` entram porque o vocabulário dele pode estar num pré-processador -
+ * um `$gray_dark` que mantivesse o `$` viraria o caminho `color.$gray.dark`, que não é um caminho.
+ */
+const clean = (name) => name.replace(/^(--|[$@])/, "").toLowerCase();
 /**
  * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e aqui a natureza do ACHADO decide.
  *
@@ -105,7 +109,31 @@ function nearestOwn(theirs, literal, kind) {
  * existente com outro valor - isso não é absorver, é repintar.
  */
 export function absorbPlan(d, theirs, have, cap = 40) {
-    const unnamed = d.repeats.filter((r) => !r.token);
+    /**
+     * A REPETIÇÃO É UM FILTRO DE RUÍDO, E RUÍDO É UMA PROPRIEDADE DA ESCALA - não do valor.
+     *
+     * Ordenar por repetição está certo onde a deriva se concentra: no `~/projects/web-subscribe` são
+     * 858 valores distintos escritos à mão, e mostrar os 40 mais repetidos é o que transforma isso numa
+     * fila de trabalho. Num projeto que acabou de nascer, o mesmo corte apaga o projeto inteiro.
+     *
+     * Medido em 07/09 sobre três populações:
+     *
+     *     ~/projects/web-subscribe   858 distintos   484 repetidos   362 apareciam uma vez só
+     *     ~/projects/web-onboarding   52 distintos    21 repetidos    29 apareciam uma vez só
+     *     create-next-app real          4 distintos     0 repetidos     4 apareciam uma vez só
+     *
+     * Naquele último o `absorb` respondia que não havia nada a absorver, três linhas depois de o
+     * `doctor` dizer *"0 of 4 have a name waiting"*.
+     *
+     * A REGRA SAI DO TETO QUE JÁ EXISTE, e por isso não é mais um número escolhido por nós: o corte
+     * serve para ESCOLHER quando não cabe tudo. Quando tudo cabe, não há o que escolher, e esconder
+     * metade é esconder por hábito. Num repositório grande nada muda - 484 já estouram o teto sozinhos.
+     */
+    const repeated = d.repeats.filter((r) => !r.token);
+    const single = d.once.filter((r) => !r.token);
+    const unnamed = repeated.length + single.length <= cap
+        ? [...repeated, ...single]
+        : repeated;
     const entries = [];
     for (const r of unnamed) {
         if (entries.length >= cap)
@@ -133,7 +161,25 @@ export function absorbPlan(d, theirs, have, cap = 40) {
          * `var(--dashboard-white-500)` e o `absorb`, no mesmo dia, pedia que ele batizasse `#fff`. Dois
          * comandos com conselhos opostos sobre o mesmo valor.
          */
-        const theirName = nameOf(r.kind, theirs.byValue.get(normalizeValue(r.literal, theirs.rootPx)));
+        /**
+         * O NOME DELE VEM DAS DUAS FORMAS - e sem a segunda os dois comandos voltam a se contradizer.
+         *
+         * É o mesmo defeito que esta função já corrigiu uma vez, reaberto por outro caminho: o `doctor`
+         * passou a dizer *"#555 · your code calls it $gray_dark"* e o `absorb`, no mesmo repositório,
+         * pedia que ele batizasse o `#555`. Dois comandos com conselhos opostos sobre o mesmo valor.
+         *
+         * A ORDEM É A MESMA DO RESTO DA ESTEIRA: primeiro o nome que o navegador recebe, e só depois o
+         * que o pré-processador resolve. Onde ele nomeia nas duas formas, ganha a custom property.
+         *
+         * E aqui o nome compilado NÃO é um beco: o caminho que sai dele vira um token de verdade na
+         * fundação, que o navegador recebe - então as ocorrências em `.tsx`, que nunca poderiam receber
+         * um `$`, ficam trocáveis pelo caminho que já existe (`absorb` -> `upgrade` -> `doctor --fix`).
+         * Medido em 07/09 no `~/projects/web-subscribe`: 323 ocorrências têm nome dele, e só 52 delas
+         * estão num arquivo que poderia escrever o `$` diretamente.
+         */
+        const value = normalizeValue(r.literal, theirs.rootPx);
+        const theirName = nameOf(r.kind, theirs.byValue.get(value)) ??
+            nameOf(r.kind, theirs.compiledAway.get(value)?.map((c) => c.name));
         const path = pathFor(r.kind, theirName);
         /** "≈ perto de um token seu" só interessa a quem não tem um EXATO - com o nome na mão, a dica
          *  vira ruído, e no arquivo de proposta ela vira uma segunda opção que não é opção. */
@@ -151,7 +197,11 @@ export function absorbPlan(d, theirs, have, cap = 40) {
             ...(near ? { near } : {}),
         });
     }
-    return { entries, more: Math.max(0, unnamed.length - entries.length) };
+    return {
+        entries,
+        more: Math.max(0, unnamed.length - entries.length),
+        unnamed: d.repeats.length + d.once.length,
+    };
 }
 /** Quantas linhas da proposta ainda precisam de um nome humano. */
 export const needingName = (plan) => plan.entries.filter((e) => !e.path);
@@ -166,9 +216,21 @@ export function describeAbsorb(plan) {
     const ready = plan.entries.filter((e) => e.path);
     const pending = needingName(plan);
     const lines = [];
+    /**
+     * VAZIO POR DOIS MOTIVOS OPOSTOS, e a frase afirmava só um.
+     *
+     * "every repeated value already has a name" é notícia boa. Mas a lista também fica vazia quando não
+     * há valor NENHUM escrito à mão - e aí a frase de cima descreve um repositório que não é o dele.
+     * Medido em 07/09 numa cópia de `create-next-app`: 4 valores sem nome, e esta era a resposta.
+     *
+     * A distinção não é cosmética: um manda seguir em frente, o outro diz que o comando não tem
+     * trabalho porque o projeto não tem deriva. Duas conversas diferentes.
+     */
     if (plan.entries.length === 0)
         return [
-            "Nothing to absorb: every repeated value your code writes by hand already has a name in the system.",
+            plan.unnamed > 0
+                ? `Nothing to absorb here: the ${plan.unnamed} value${plan.unnamed === 1 ? "" : "s"} written by hand ${plan.unnamed === 1 ? "already has" : "already have"} a name in your system.`
+                : "Nothing to absorb: no design value in this project is written by hand.",
         ];
     /**
      * A SEÇÃO DOS QUE JÁ TÊM NOME SÓ EXISTE SE ALGUM TIVER - e no dia 1 nenhum tem.
@@ -187,9 +249,18 @@ export function describeAbsorb(plan) {
         const close = pending.filter((e) => e.near);
         if (ready.length > 0)
             lines.push("");
+        /**
+         * "REPEATED" SÓ QUANDO ELES SE REPETEM - e desde que o corte por repetição deixou de valer para
+         * projeto pequeno, essa palavra passou a descrever um repositório que não é o dele.
+         *
+         * Medido em 07/09 numa cópia de `create-next-app`: a linha dizia *"4 repeated values"* sobre
+         * quatro valores que aparecem uma vez cada. Uma palavra errada na primeira linha do comando gasta
+         * a credibilidade das outras dez.
+         */
+        const everyOneRepeats = pending.every((e) => e.count > 1);
         lines.push(ready.length > 0
             ? `${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`
-            : `${pending.length} repeated values, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
+            : `${pending.length} ${everyOneRepeats ? "repeated values" : "values written by hand"}, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
         for (const e of pending.slice(0, 8))
             lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
         if (pending.length > 8)

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

@@ -3,8 +3,10 @@ import { dirname, join, resolve } from "node:path";
 import { absorbPlan, describeAbsorb, needingName, } from "../absorb-plan.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
+import { withTheirNames } from "../doctor/their-names.js";
 import { measuredScope, scopePaths } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
+import { resolveDeps, tailwindMajor } from "../stack.js";
 import { loadSystem, walkAll } from "./doctor.js";
 /**
  * `synthesisui absorb` - O SISTEMA APRENDE O DESIGN QUE O CÓDIGO JÁ TEM.
@@ -66,12 +68,28 @@ export async function absorb(opts) {
      * ideia primeiro e ficou com a implementação de todo mundo.
      */
     const theirs = installed.theirs;
+    /**
+     * SEM SISTEMA NOSSO, A TABELA DA VARREDURA É A DELE - a mesma queda que o `doctor` já faz.
+     *
+     * O QUE ACONTECIA: este comando varria com `installed.table`, que sem sistema instalado é a tabela
+     * VAZIA. Então nada tinha nome, nem o que o próprio código dele nomeia - e a linha
+     * `--background: #ffffff`, que é onde o token dele NASCE, entrava na proposta como um valor solto
+     * a ser batizado. Medido em 07/09 numa cópia de `create-next-app`: 4 das 8 entradas eram as
+     * declarações dos tokens dele, e duas delas já traziam `theirName` preenchido - a proposta pedindo
+     * um nome para o que ela mesma acabara de dizer que já tem um.
+     *
+     * O `doctor` resolve isto há tempos, e a linha é literalmente a dele: quando não há nada nosso, o
+     * vocabulário dele é o único que existe, e é contra ele que a medição acontece.
+     */
+    const table = installed.table.byName.size > 0
+        ? installed.table
+        : withTheirNames(theirs, theirs);
     const reports = [];
     for await (const file of walkAll(roots)) {
         const source = await readFile(file, "utf8").catch(() => null);
         if (source === null)
             continue;
-        reports.push(scanSource(file.slice(root.length + 1), source, installed.table));
+        reports.push(scanSource(file.slice(root.length + 1), source, table));
     }
     const plan = absorbPlan(diagnose(reports), theirs, pathsInSystem(installed.documents), opts.cap ?? 40);
     console.log(section(hasSystem
@@ -173,13 +191,36 @@ async function sendProposal(root, path, registry) {
         console.log(body(paint.dim(proposal.slug
             ? "Your config says absorbed values belong in your CSS, so nothing was sent."
             : "You have no system yet, so these belong in your own CSS - nothing was sent, and nothing needed an account.")));
+        /**
+         * NUM TAILWIND v4, `:root` DECLARA A VARIÁVEL E NÃO GERA A CLASSE.
+         *
+         * O QUE ELE VIVIA: nomeava `#383838` de `color.ink.700`, colava o bloco que este comando
+         * imprime, e `text-ink-700` continuava não existindo. A variável estava lá, o doctor a
+         * reconhecia - e o código dele não tinha como usá-la. A metade visível da promessa não chegava.
+         *
+         * É a mesma lei que a `INV-VOLTA-13` já enuncia do outro lado da esteira: *"no Tailwind v4 só
+         * `@theme` gera utilitário"*. A folha que a plataforma instala sabe disso desde 23/08; o bloco
+         * que a plataforma manda ELE colar não sabia.
+         *
+         * E A SINTAXE SAI DO PROJETO, nunca de um padrão nosso - `tailwindMajor` já existe e o
+         * comentário dele diz por quê: *"gerar a sintaxe de uma para um projeto da outra produz um
+         * arquivo que o build DELE não entende, e é o pior tipo de saída, porque parece certa até
+         * alguém compilar"*. Sem Tailwind, ou na v3, `:root` continua sendo a resposta certa: lá o
+         * utilitário nasce do `tailwind.config`, não do CSS.
+         */
+        const major = tailwindMajor(await resolveDeps(root));
+        const block = major === 4 ? "@theme" : ":root";
         console.log("");
-        console.log("  :root {");
+        console.log(`  ${block} {`);
         for (const e of ready)
             console.log(`    --${e.path.replace(/\./g, "-")}: ${e.value};`);
         console.log("  }");
         console.log("");
-        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
+        console.log(body(major === 4
+            ? "In `@theme` and not `:root`: on Tailwind v4 only `@theme` generates the utility, so this is what makes `text-ink-700` exist in your code."
+            : "The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
+        if (major === 4)
+            console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
         return;
     }
     const token = await readToken();

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/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.
  *
@@ -399,14 +400,20 @@ async function harvestOwnTokens(roots,
  *  e `4px` deixaria de casar com `0.25rem` de um lado só. */
 measured) {
     let css = "";
+    /** UMA A UMA, e não só concatenadas: a regra de escopo de `their-compiled-names.ts` decide pelo
+     *  `@import` de um arquivo no outro, e a concatenação apaga de qual arquivo cada linha veio. */
+    const sheets = new Map();
     for await (const file of walkAll(roots)) {
         if (!/\.(css|scss|sass|less)$/i.test(file))
             continue;
-        css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+        const source = await readFile(file, "utf8").catch(() => "");
+        sheets.set(file, source);
+        css += `\n${source}`;
     }
     return buildTable({
         css,
         source: "yours",
+        sheets,
         rootPx: measured?.px,
         rootFrom: measured?.from ?? null,
     });
@@ -463,10 +470,27 @@ function verdict(d, hasSystem, overruled, conflicts) {
      */
     if (!hasSystem) {
         const distinct = new Set(d.findings.map((f) => f.literal.toLowerCase()));
+        /**
+         * O QUE O CÓDIGO DELE JÁ NOMEIA - e sem esta linha o relatório se contradiz.
+         *
+         * "none of them has a name yet" é o fecho de um projeto sem sistema, e ele era verdade enquanto
+         * a plataforma só lia custom properties. Agora o detalhe imprime `#555 · your code calls it
+         * $gray_dark` três linhas acima: o resumo dizendo que nada tem nome, sobre um valor que a linha
+         * de cima acabou de nomear, é o defeito que faz alguém desconfiar do relatório inteiro.
+         *
+         * E o número muda a decisão dele: quem já batizou metade dos valores no Sass não está no dia
+         * zero - ele está a um `absorb` de trazer esses nomes para um vocabulário que o navegador
+         * recebe, o que é uma conversa diferente de "escolha o sistema de alguém".
+         */
+        const spoken = new Set(d.findings
+            .filter((f) => f.theirCompiledName)
+            .map((f) => f.literal.toLowerCase()));
         return [
             ...head,
             body(`${distinct.size} distinct design values are written by hand here.`),
-            body("No design system is installed, so none of them has a name yet."),
+            spoken.size === 0
+                ? body("No design system is installed, so none of them has a name yet.")
+                : body(`No design system is installed, but your own code already names ${spoken.size} of them - in Sass or Less, which the browser never receives.`),
             "",
             body("Name them yourself - this reads them and asks you for the words:"),
             snippet(["npx synthesisui@latest absorb"]),
@@ -698,7 +722,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 +987,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 +1031,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")));
         }
     }
     /**
@@ -1500,9 +1557,19 @@ export async function doctor(opts) {
                     ? `→ no ${x.kind} named for it · the value lives as ${x.token}`
                     : nameToWrite(x)
                         ? `→ ${nameToWrite(x)}${alsoNamed(x)}`
-                        : near
-                            ? `→ nearest is ${near.theirs ?? near.name} (${near.value})`
-                            : "→ no token holds this value yet";
+                        : /**
+                           * O CÓDIGO DELE JÁ NOMEIA ISTO, e a linha dizia que nada nomeava.
+                           *
+                           * Vem antes de `near` porque um nome EXATO que ele escreveu vale mais que o degrau
+                           * mais próximo de outra coisa. Sem seta de troca: `$gray_dark` não existe num `.tsx`
+                           * e a troca segura depende de duas provas que esta camada não tem - ver
+                           * `TheirName.writable`.
+                           */
+                            x.theirCompiledName
+                                ? `· your code calls it ${x.theirCompiledName}`
+                                : near
+                                    ? `→ nearest is ${near.theirs ?? near.name} (${near.value})`
+                                    : "→ no token holds this value yet";
                 say(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
             }
             if (f.findings.length > shown.length) {
@@ -1857,11 +1924,25 @@ export async function doctor(opts) {
              * que NENHUM dos dois nomeia o valor. É isso que a linha passa a dizer, e é o que separa esta
              * fila da anterior: aquela tem nome esperando, esta precisa de um.
              */
-            what: near
-                ? `${r.literal} - name it, or snap to ${near.theirs ?? near.name}`
-                : r.crossFamily
-                    ? `${r.literal} - no ${r.kind} named for it, and the value lives as ${r.token} in another family`
-                    : `${r.literal} - no name for it, here or in your CSS`,
+            /**
+             * O SEU CÓDIGO JÁ NOMEIA ISTO, e a linha dizia o contrário.
+             *
+             * "no name for it, here or in your CSS" é uma afirmação sobre o repositório DELE, e ela era
+             * falsa sempre que o nome estava num pré-processador: medido em 07/09 no `web-subscribe`,
+             * `#555` é `$gray_dark` em `css/colors.scss` e aparecia como "sem nome" em 27 arquivos.
+             *
+             * A linha DIZ o nome e não convida a trocar - `$gray_dark` não existe num `.tsx`, e a troca
+             * segura depende de o arquivo de destino compilar aquele pré-processador e importar aquela
+             * folha, que é o próximo passo desta frente. Dizer o que existe já muda a decisão dele; trocar
+             * sem essas duas provas quebraria o build.
+             */
+            what: r.theirCompiledName
+                ? `${r.literal} - your code calls it ${r.theirCompiledName} (no fix: it never reaches the browser)`
+                : near
+                    ? `${r.literal} - name it, or snap to ${near.theirs ?? near.name}`
+                    : r.crossFamily
+                        ? `${r.literal} - no ${r.kind} named for it, and the value lives as ${r.token} in another family`
+                        : `${r.literal} - no name for it, here or in your CSS`,
             size: `${r.files} file${r.files === 1 ? "" : "s"}`,
             cheap: false,
         });

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

@@ -540,7 +540,18 @@ function scanCore(file, source, table) {
                 ...(/(?<!r)em$/i.test(literal.trim())
                     ? { fontRelative: true }
                     : {}),
-                ...(theirs ? { theirToken: theirs.name } : {}),
+                ...(theirs?.writable ? { theirToken: theirs.name } : {}),
+                /**
+                 * O NOME QUE SÓ SE DIZ - `$gray_dark` do Sass, `@brand` do Less.
+                 *
+                 * Separado de `theirToken` porque aquele campo é o que o `--fix` ESCREVE, e um nome de
+                 * pré-processador escrito num `.tsx` é código quebrado. Aqui ele serve ao relatório, que
+                 * deixa de afirmar "no name for it, here or in your CSS" sobre um valor que o código dele
+                 * nomeia - a afirmação era sobre o repositório DELE, e era falsa.
+                 */
+                ...(theirs && !theirs.writable
+                    ? { theirCompiledName: theirs.name }
+                    : {}),
                 ...(theirs?.also.length ? { theirAlso: theirs.also } : {}),
                 /**
                  * A COINCIDÊNCIA VIAJA COM O ACHADO - ver `tokenMatch`.
@@ -737,6 +748,9 @@ export function diagnose(files) {
                 kind: f.kind,
                 token: f.token,
                 ...(f.theirToken ? { theirToken: f.theirToken } : {}),
+                ...(f.theirCompiledName
+                    ? { theirCompiledName: f.theirCompiledName }
+                    : {}),
                 ...(f.theirAlso?.length ? { theirAlso: f.theirAlso } : {}),
                 ...(f.fontRelative ? { fontRelative: true } : {}),
                 count: 1,
@@ -745,25 +759,31 @@ export function diagnose(files) {
             });
         }
     }
-    const repeats = [...byLiteral.entries()]
+    const everyLiteral = [...byLiteral.entries()]
         .map(([key, v]) => ({
         literal: key.slice(key.indexOf(":") + 1),
         kind: v.kind,
         token: v.token,
         ...(v.theirToken ? { theirToken: v.theirToken } : {}),
+        ...(v.theirCompiledName
+            ? { theirCompiledName: v.theirCompiledName }
+            : {}),
         ...(v.theirAlso?.length ? { theirAlso: v.theirAlso } : {}),
         ...(v.fontRelative ? { fontRelative: true } : {}),
         count: v.count,
         files: v.files.size,
         ...(v.crossFamily ? { crossFamily: true } : {}),
     }))
-        .filter((r) => r.count > 1)
         .sort((a, b) => b.count - a.count);
+    const repeats = everyLiteral.filter((r) => r.count > 1);
+    /** Ver `Diagnosis.once` - o que o corte por repetição deixa de fora. */
+    const once = everyLiteral.filter((r) => r.count === 1);
     return {
         // A file with a phantom name and no drift has nothing to say by the old
         // measure and the worst thing to say by the new one. Both keep it.
         files: files.filter((f) => f.findings.length > 0 || (f.phantoms?.length ?? 0) > 0),
         findings: flat,
+        once,
         counts,
         /**
          * QUANTOS JÁ TÊM NOME NESTE REPOSITÓRIO - e o dele conta.

package/dist/doctor/their-compiled-names.js

@@ -0,0 +1,121 @@
+import { dirname, join, resolve } from "node:path";
+/**
+ * OS NOMES DELE QUE SOMEM NA COMPILAÇÃO - e que a plataforma afirmava não existir.
+ *
+ * O QUE O CLIENTE VIA. Um projeto que declara `$gray_dark: #555` em `css/colors.scss` e escreve
+ * `#555` em dezenas de arquivos recebia, do nosso relatório: *"#555 - no name for it, here or in
+ * your CSS"*. A frase é uma afirmação sobre o repositório DELE, e ela era falsa. Medido em 07/09 no
+ * `~/projects/web-subscribe`: `doctor` dizia `13 tokens found` num projeto com 27 nomes de cor
+ * declarados e partilhados, e 323 ocorrências ficavam sem o nome que o próprio código já lhes dá.
+ *
+ * POR QUE A PLATAFORMA NÃO OS VIA, e não era descuido: a colheita lê custom properties (`--x`), que
+ * é o que o navegador recebe. Uma variável de pré-processador - `$x` no Sass, `@x` no Less - resolve
+ * em tempo de compilação e não chega ao CSS final. Ela é vocabulário dele para LER, nunca endereço
+ * para APONTAR: escrever `var($gray_dark)` não existe.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * A REGRA QUE SEPARA A FEATURE DO DEFEITO: ESCOPO.
+ *
+ * Uma custom property em `:root` é global por construção - é isso que a torna vocabulário. Um `$x` no
+ * topo de um arquivo é uma constante DAQUELE arquivo, e tratar as duas como a mesma coisa inventa
+ * vocabulário em vez de ler o que existe.
+ *
+ * Medido no mesmo repositório, e a diferença é a feature inteira:
+ *
+ *     323  ocorrências ganham o nome certo   ($ declarado em folha que outra folha importa)
+ *    1085  ganhariam um nome FALSO           ($color e $primary-color declarados dentro de um
+ *                                             styles.module.scss de um componente - `$color: #FFF`
+ *                                             existe em dois módulos diferentes, e `#fff` aparece
+ *                                             596 vezes no projeto inteiro)
+ *
+ * Então só conta o que é PARTILHADO: um arquivo que outro arquivo importa foi escrito para ser
+ * vocabulário comum, e quem decide isso é o `@import`/`@use`/`@forward` dele - não uma convenção de
+ * nome de arquivo nossa, que seria a forma de fixar o hábito de um repositório dentro do produto.
+ */
+/** As extensões cujo vocabulário some antes do navegador. */
+const PREPROCESSED = /\.(scss|sass|less)$/i;
+/** `$nome: valor;` no Sass, `@nome: valor;` no Less - no topo do arquivo, fora de qualquer bloco. */
+const DECLARATION = /^[ \t]*([$@][a-zA-Z0-9_-]+)[ \t]*:[ \t]*([^;{}]+);/gm;
+/**
+ * `!default` É A MARCA DA PRÓPRIA LINGUAGEM PARA "ISTO É O PADRÃO DE UMA BIBLIOTECA".
+ *
+ * Em Sass ele significa literalmente *este valor vale se quem me usa não definiu outro* - a forma
+ * como um pacote publica vocabulário configurável. Um valor que ELE decidiu não carrega `!default`,
+ * e é essa diferença que separa a decisão dele do default de um pacote que alguém copiou para
+ * dentro do repositório.
+ *
+ * Medido em 07/09 no `~/projects/web-subscribe`, que tem `bootstrap-sass` e `ionicons` copiados para
+ * `css/`: dos 1185 nomes que a varredura encontra, 1125 são desses dois pacotes e TODOS trazem
+ * `!default`. Sem esta porta, o relatório responderia que o `#555` dele "se chama
+ * `$navbar-default-link-active-color`" - o vocabulário de uma biblioteca apresentado como o dele,
+ * que é o oposto exato do que este leitor existe para fazer.
+ *
+ * O LADO SEGURO DO ERRO, declarado: um projeto que use `!default` no PRÓPRIO vocabulário perde esses
+ * nomes e volta a ver "no name for it". Deixar de nomear o que existe custa uma linha de relatório;
+ * batizar o valor dele com a palavra de um pacote custa a confiança na próxima linha.
+ */
+const LIBRARY_DEFAULT = /!\s*default\b/i;
+/** `@import "colors"`, `@use "./colors" as c`, `@forward "colors"`. */
+const REFERENCE = /@(?:import|use|forward)\s+["']([^"']+)["']/g;
+/**
+ * QUAIS FOLHAS OUTRA FOLHA IMPORTA - a prova de que aquele arquivo é vocabulário comum.
+ *
+ * A resolução segue o que o Sass faz: a extensão é opcional e o parcial pode ter o `_` na frente.
+ * Um especificador que não aponta para nenhum arquivo do projeto é um pacote (`@import "bootstrap"`),
+ * e pacote não é vocabulário dele.
+ */
+export function sharedSheets(sheets) {
+    const known = new Set(sheets.keys());
+    const shared = new Set();
+    for (const [path, source] of sheets) {
+        const dir = dirname(path);
+        for (const [, spec] of source.matchAll(REFERENCE)) {
+            const bare = spec.replace(/\.(scss|sass|less|css)$/i, "");
+            const base = bare.split("/").pop() ?? bare;
+            const parent = bare.slice(0, bare.length - base.length);
+            for (const candidate of [
+                `${bare}.scss`,
+                `${bare}.sass`,
+                `${bare}.less`,
+                `${bare}.css`,
+                join(parent, `_${base}.scss`),
+                join(parent, `_${base}.sass`),
+                join(parent, `_${base}.less`),
+            ]) {
+                const abs = resolve(dir, candidate);
+                if (known.has(abs)) {
+                    shared.add(abs);
+                    break;
+                }
+            }
+        }
+    }
+    return shared;
+}
+/**
+ * O VOCABULÁRIO PARTILHADO QUE O NAVEGADOR NUNCA VÊ.
+ *
+ * A primeira declaração vence, a mesma regra que a colheita de custom properties usa: uma folha
+ * posterior sobrescrevendo uma anterior é cascata, e este leitor não vê cascata.
+ */
+export function compiledNames(sheets) {
+    const shared = sharedSheets(sheets);
+    const out = [];
+    const seen = new Set();
+    for (const [path, source] of sheets) {
+        if (!PREPROCESSED.test(path) || !shared.has(path))
+            continue;
+        for (const [, name, value] of source.matchAll(DECLARATION)) {
+            if (seen.has(name) || LIBRARY_DEFAULT.test(value))
+                continue;
+            seen.add(name);
+            /** `!global` diz onde a atribuição vale, não o que ela vale - sai do valor e não da lista. */
+            out.push({
+                name,
+                value: value.replace(/!\s*global\b/i, "").trim(),
+                file: path,
+            });
+        }
+    }
+    return out;
+}

package/dist/doctor/their-names.js

@@ -47,7 +47,12 @@ import { FAMILY_PREFIX, familySays, formDecides, normalizeValue, UNAMBIGUOUS, }
  * que o próprio css dele nomeia `--dashboard-font-family`. É pouco, e é o único grupo que sobrou do
  * item que eu tinha nomeado - os `em` saíram na leva anterior.
  */
-const segments = (name) => name.replace(/^--/, "").split("-");
+/**
+ * O nome sem o sigilo, em pedaços. `$` e `@` entram porque o vocabulário dele pode estar num
+ * pré-processador (ver `their-compiled-names.ts`), e um `$gray-dark` que não perdesse o `$` nunca
+ * casaria segmento nenhum no desempate - o critério existiria e nunca alcançaria esses nomes.
+ */
+const segments = (name) => name.replace(/^(--|[$@])/, "").split("-");
 /**
  * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e são 18 no repo real.
  *
@@ -132,13 +137,20 @@ roles) {
  * sistema do dono, `#f59e0b` é `--color-tier-gold` E `--color-feedback-warning` - dois conceitos
  * dele, gamificação e estado -, e o relatório dizia `→ {color.tier-gold}` como se fosse fato.
  */
-function escolha(candidates, ours, convention, roles) {
+function escolha(candidates, ours, convention, roles, 
+/** `false` para nome de pré-processador - ver `TheirName.writable`. */
+writable = true) {
     const name = pick(candidates, ours, convention, roles);
-    return { name, also: candidates.filter((c) => c !== name) };
+    return { name, also: candidates.filter((c) => c !== name), writable };
 }
 export function theirNames(ours, theirs) {
     const out = new Map();
-    if (theirs.byName.size === 0)
+    /**
+     * AS DUAS FONTES, e não só a primeira: um projeto que declara o vocabulário INTEIRO em Sass tem
+     * `byName` vazio e mesmo assim tem nomes para dizer. Sair aqui devolvia mapa vazio para ele, e o
+     * relatório voltava a afirmar que o repositório não nomeia um valor que o repositório nomeia.
+     */
+    if (theirs.byName.size === 0 && theirs.compiledAway.size === 0)
         return out;
     /**
      * OS PAPÉIS QUE ESTE SISTEMA DECLARA, derivados dos NOSSOS nomes - ver o critério 2 de `pick`.
@@ -205,6 +217,29 @@ export function theirNames(ours, theirs) {
             out.set(key, escolha(candidates, null, convention, roles));
         }
     }
+    /**
+     * POR ÚLTIMO, O QUE SÓ SE DIZ - e ser o último é a regra, não a ordem do arquivo.
+     *
+     * Onde ele nomeia o mesmo valor nas duas formas, quem ganha é a custom property: ela resolve no
+     * navegador, o `--fix` pode escrevê-la e ela sobrevive a qualquer mudança de pré-processador. Só
+     * quando NENHUM nome que o navegador recebe segura aquele valor é que o nome compilado entra - e
+     * entra marcado como não escrevível.
+     *
+     * A mesma porta da forma vale aqui: `UNAMBIGUOUS` deixa passar o que a FORMA já classifica (cor,
+     * duração, pilha de fontes) e deixa o comprimento cru de fora. Sem isso, um `$mobile_gutter: 10px`
+     * seria oferecido como o nome de todo `10px` do projeto - medido em 07/09 no `web-subscribe`, onde
+     * `10px` aparece em 102 arquivos e quase nenhum é um gutter.
+     */
+    for (const [value, names] of theirs.compiledAway) {
+        for (const [kind, form] of Object.entries(UNAMBIGUOUS)) {
+            if (!form.test(value))
+                continue;
+            const key = `${kind}:${value}`;
+            if (out.has(key))
+                continue;
+            out.set(key, escolha(names.map((n) => n.name), null, convention, roles, false));
+        }
+    }
     return out;
 }
 /**

package/dist/doctor/tokens.js

@@ -13,6 +13,7 @@
  */
 import { DEFAULT_ROOT_PX } from "./root-size.js";
 import { parseSchemeBlocks } from "./scheme-blocks.js";
+import { compiledNames } from "./their-compiled-names.js";
 export const EMPTY_TABLE = {
     source: null,
     name: null,
@@ -24,6 +25,7 @@ export const EMPTY_TABLE = {
     rootFrom: null,
     aliases: new Map(),
     declared: new Set(),
+    compiledAway: new Map(),
     keyframes: new Set(),
 };
 const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
@@ -318,6 +320,17 @@ export function buildTable(input) {
     const byName = source === "installed"
         ? parseTokens(input.css)
         : parseRootTokens(input.css);
+    /**
+     * O VOCABULÁRIO DELE QUE NÃO CHEGA AO NAVEGADOR, somado ao que chega.
+     *
+     * Entra DEPOIS das custom properties e sem sobrescrever nenhuma: onde as duas formas nomeiam o
+     * mesmo valor, o nome que o navegador recebe é o que resolve, e é ele que a folha pode apontar.
+     */
+    const compiled = source === "installed" || !input.sheets ? [] : compiledNames(input.sheets);
+    const compiledAway = new Map();
+    for (const one of compiled)
+        if (!byName.has(one.name))
+            compiledAway.set(one.name, one);
     /**
      * Built from the RESOLVED map, not from `byName`. A semantic role that
      * aliases a primitive has to be findable by the primitive's value, or the
@@ -337,6 +350,24 @@ export function buildTable(input) {
      */
     const raw = source === "installed" ? parseTokensWithAliases(input.css) : new Map();
     const isAlias = (name) => /^var\(/.test((raw.get(name) ?? "").trim());
+    /**
+     * OS NOMES QUE SÓ SE DIZEM, indexados pelo MESMO valor normalizado das outras tabelas.
+     *
+     * Fora de `byName` e de `byValue` de propósito: aquelas duas respondem "o meu sistema nomeia
+     * isto?", que é a pergunta da cobertura e do `--fix`. Um nome que o navegador nunca recebe não
+     * pode entrar em nenhuma das duas - inflaria a contagem de tokens dele (medido em 07/09 no
+     * `web-subscribe`: 13 viraria 1198, e 1125 dos acrescentados eram bootstrap e ionicons copiados
+     * para dentro do repositório) e ofereceria ao `--fix` um nome que quebra um `.tsx`.
+     */
+    const byCompiledValue = new Map();
+    for (const one of compiledAway.values()) {
+        const key = normalizeValue(one.value, rootPx);
+        const list = byCompiledValue.get(key);
+        if (list)
+            list.push(one);
+        else
+            byCompiledValue.set(key, [one]);
+    }
     const byValue = new Map();
     for (const [name, value] of resolved) {
         const key = normalizeValue(value, rootPx);
@@ -360,6 +391,7 @@ export function buildTable(input) {
         /** Vazio até `withTheirNames` ler o vocabulário dele - ver `their-names.ts`. */
         aliases: new Map(),
         declared: parseDeclaredNames(input.css),
+        compiledAway: byCompiledValue,
         keyframes: new Set([...input.css.matchAll(/@keyframes\s+([a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
     };
 }
@@ -418,7 +450,11 @@ kind) {
     const theirs = kind
         ? table.aliases.get(`${kind}:${normalizeValue(best.value, table.rootPx)}`)
         : undefined;
-    return theirs ? { ...best, theirs: theirs.name } : best;
+    /**
+     * SÓ UM NOME ESCREVÍVEL - esta linha convida a trocar (`snap to X`), e um nome de pré-processador
+     * não pode ir para o código dele. Ver `TheirName.writable`.
+     */
+    return theirs?.writable ? { ...best, theirs: theirs.name } : best;
 }
 /**
  * The family a token belongs to, from the drift it was found in.

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.389";
+export const MATERIALISER_SINCE = "0.16.390";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

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/dist/stack.js

@@ -235,11 +235,39 @@ classStyle) {
  *
  * `null` quando o pacote não está lá ou quando a faixa não diz um número - um intervalo que não se
  * resolve é ausência de resposta, e supor a v4 seria escolher o mais novo por conveniência nossa.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O MAIOR SOZINHO É UMA FAIXA, e exigir o ponto apagava metade dos projetos v4.
+ *
+ * A primeira versão desta função casava `(\d+)\.` - um número SEGUIDO DE PONTO. `^4.1.2` respondia
+ * 4; `^4`, que é exatamente o que o `create-next-app` e o instalador do Tailwind v4 escrevem,
+ * respondia `null`. E `null` aqui não é neutro: é a plataforma dizendo *não sei qual versão* sobre um
+ * projeto que declara a versão na primeira linha do `package.json` dele.
+ *
+ * Medido em 07/09 nos sete projetos com Tailwind desta máquina:
+ *
+ *     "^4"       3 projetos   -> null    test_ds_01, web-subscribe, web-dashboard
+ *     "^3.4.1"   1 projeto    -> 3
+ *     "^3.3.5"   1 projeto    -> 3
+ *     "3.4.3"    1 projeto    -> 3
+ *     "4.1.11"   1 projeto    -> 4
+ *
+ * Os três invisíveis são os três v4 - e não por acaso: é a v4 que se instala como `^4`. Quem paga é
+ * quem começa um projeto HOJE.
+ *
+ * A AMBIGUIDADE CONTINUA VALENDO `null`, e agora ela é medida em vez de suposta: cada faixa da
+ * expressão diz um maior, e a resposta só existe quando todas dizem o MESMO. `>=3 <5` continua sendo
+ * ausência de resposta, porque é; `^4` deixa de ser, porque não é.
  */
 export function tailwindMajor(deps) {
     const raw = deps.tailwindcss;
     if (!raw)
         return null;
-    const m = /(\d+)\./.exec(raw.replace(/^[^0-9]*/, ""));
-    return m ? Number(m[1]) : null;
+    const majors = new Set();
+    for (const part of raw.split(/\s*\|\|\s*|\s+|,/).filter(Boolean)) {
+        const m = /(\d+)/.exec(part.replace(/^[^0-9]*/, ""));
+        if (m)
+            majors.add(Number(m[1]));
+    }
+    return majors.size === 1 ? [...majors][0] : null;
 }

package/dist/their-vars.js

@@ -101,7 +101,14 @@ export function pointAtTheirNames(css, theirs, resolvable) {
      * buildou não tem como provar o que resolve, e um par afirmado sem prova é pior que par nenhum.
      */
     if (!resolvable || theirs.byName.size === 0)
-        return { css, pointed: 0, pruned: 0, cycles: 0, pairs: [] };
+        return {
+            css,
+            pointed: 0,
+            pruned: 0,
+            compiledAway: 0,
+            cycles: 0,
+            pairs: [],
+        };
     const ours = buildTable({ css, source: "installed" });
     const alias = theirNames(ours, theirs);
     /**
@@ -116,6 +123,7 @@ export function pointAtTheirNames(css, theirs, resolvable) {
         bridged.set(theirName, ourName);
     let pointed = 0;
     let pruned = 0;
+    let compiledAway = 0;
     let cycles = 0;
     /** Ver `PointedAt.pairs`: o mapa sai do mesmo casamento que reescreve a linha. */
     const pairs = [];
@@ -126,9 +134,19 @@ export function pointAtTheirNames(css, theirs, resolvable) {
         const kind = Object.entries(FAMILY_KIND).find(([prefix]) => name.startsWith(prefix))?.[1];
         if (!kind)
             return line;
-        const theirName = alias.get(`${kind}:${normalizeValue(value.trim(), ours.rootPx)}`)?.name;
+        const theirs_ = alias.get(`${kind}:${normalizeValue(value.trim(), ours.rootPx)}`);
+        const theirName = theirs_?.name;
         if (!theirName || theirName === name)
             return line;
+        /**
+         * UM NOME DE PRÉ-PROCESSADOR NÃO É UM ENDEREÇO. `var($gray_dark)` não existe em CSS nenhum,
+         * então a linha fica com o valor - e a recusa se conta pela SUA causa, não como se o build
+         * dele tivesse podado um token que ele pode voltar a usar.
+         */
+        if (!theirs_.writable) {
+            compiledAway += 1;
+            return line;
+        }
         /**
          * A PONTE JÁ APONTA PARA CÁ - então apontar de volta fecha um ciclo, e um ciclo não deixa o
          * valor errado: deixa a propriedade INVÁLIDA. A utility dele já resolve pelo nosso token, que é
@@ -146,7 +164,7 @@ export function pointAtTheirNames(css, theirs, resolvable) {
         pairs.push({ ours: name, theirs: theirName, value: value.trim() });
         return `${indent}${name}${sep}var(${theirName});`;
     });
-    return { css: out, pointed, pruned, cycles, pairs };
+    return { css: out, pointed, pruned, compiledAway, cycles, pairs };
 }
 /**
  * O PREFIXO DA NOSSA VARIÁVEL -> A FAMÍLIA, e a chave que `theirNames` devolve é `<família>:<valor>`.
@@ -171,7 +189,14 @@ const FAMILY_KIND = {
 export async function pointTokensAtTheirNames(root, payload) {
     const css = payload.artifacts["tokens.css"] ?? "";
     if (!css)
-        return { css, pointed: 0, pruned: 0, cycles: 0, pairs: [] };
+        return {
+            css,
+            pointed: 0,
+            pruned: 0,
+            compiledAway: 0,
+            cycles: 0,
+            pairs: [],
+        };
     const [theirs, resolvable] = await Promise.all([
         harvestTheirCss(root),
         resolvableVars(root),
@@ -190,6 +215,9 @@ async function harvestTheirCss(root) {
         "_synthesisui",
     ]);
     let css = "";
+    /** As folhas UMA A UMA, porque a regra de escopo de `their-compiled-names.ts` precisa saber qual
+     *  arquivo importa qual - a concatenação apaga exatamente essa informação. */
+    const sheets = new Map();
     const walk = async (dir) => {
         for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
             if (skip.has(entry.name) || entry.name.startsWith("."))
@@ -197,12 +225,15 @@ async function harvestTheirCss(root) {
             const path = join(dir, entry.name);
             if (entry.isDirectory())
                 await walk(path);
-            else if (/\.(css|scss|sass|less)$/i.test(entry.name))
-                css += `\n${await readFile(path, "utf8").catch(() => "")}`;
+            else if (/\.(css|scss|sass|less)$/i.test(entry.name)) {
+                const source = await readFile(path, "utf8").catch(() => "");
+                sheets.set(path, source);
+                css += `\n${source}`;
+            }
         }
     };
     await walk(root);
-    return buildTable({ css, source: "yours" });
+    return buildTable({ css, source: "yours", sheets });
 }
 /**
  * AS LINHAS QUE APONTAM PARA UM NOME DELE QUE NÃO EXISTE MAIS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.389",
+  "version": "0.16.394",
   "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.`;
-}