synthesisui 0.16.346 → 0.16.349

package/dist/commands/add.js

@@ -3,9 +3,11 @@ 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 { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
 import { censusScope } from "../measured-scope.js";
+import { recallAvailable } from "../memory/availability.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { repoStateOf } from "../repo-state.js";
@@ -13,6 +15,7 @@ import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.
 import { detectStack } from "../stack.js";
 import { onlyWhatMatched } from "../their-theme.js";
 import { pointTokensAtTheirNames } from "../their-vars.js";
+import { tracksAnyOf } from "../tracked.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
  *
@@ -184,6 +187,16 @@ export async function detectAppDirs(root, pagesDir) {
  * stable root re-exports (tokens.css/theme.css) and a `.lock` at it, and updates
  * CLAUDE.md. Older version folders are kept for rollback/diff.
  */
+/**
+ * ESTE REPOSITÓRIO VESTE SHADCN? - `components.json` é o arquivo que o próprio shadcn escreve.
+ *
+ * Uma pergunta, uma resposta: ela decide se o adaptador é ESCRITO e se ele é MENCIONADO. Enquanto
+ * eram duas leituras, o terminal dizia a verdade (só citava para quem tem) e a escrita plantava o
+ * arquivo em todo mundo - a pior combinação, porque a prosa parecia certa.
+ */
+async function wearsShadcn(root) {
+    return access(join(root, "components.json")).then(() => true, () => false);
+}
 export async function add(slug, opts) {
     const base = resolveRegistry(opts.registry);
     const projectRoot = opts.dir ?? process.cwd();
@@ -219,7 +232,26 @@ export async function add(slug, opts) {
      */
     const aligned = onlyWhatMatched(payload.artifacts["theme.css"] ?? "", new Set(theirVars.pairs.map((p) => p.ours)));
     // 1. server artifacts (tokens.css, theme.css, …) → pinned version folder
+    /**
+     * O ADAPTADOR DO SHADCN SÓ VIAJA PARA QUEM TEM SHADCN - e o sinal já existia.
+     *
+     * O QUE O CLIENTE PERCEBIA. `shadcn.css` caía na pasta de todo mundo, inclusive de quem nunca
+     * usou shadcn: um arquivo de uma stack que não é a dele, que ele não pediu e que nada no
+     * repositório dele importa. MEDIDO em 01/09 no `codelevel` - nenhum `@radix-ui`, nenhum
+     * `components/ui`, nenhum `components.json` - e os 2,3 KB estavam lá.
+     *
+     * `components.json` É O SINAL, e ele já decidia se o `add` MENCIONA o adaptador no terminal
+     * (28/07). Só a escrita não perguntava - então o produto dizia a verdade em voz alta e plantava o
+     * arquivo em silêncio. Agora a mesma pergunta responde às duas.
+     *
+     * É a régua que o compilador já aplica aos tokens (`reachableTokens` descarta o que nada
+     * referencia), levada ao arquivo inteiro: quem, NESTE repositório, lê isto?
+     */
+    const wantsShadcn = await wearsShadcn(projectRoot);
+    const skipped = !wantsShadcn && "shadcn.css" in payload.artifacts;
     for (const [filename, content] of Object.entries(payload.artifacts)) {
+        if (filename === "shadcn.css" && !wantsShadcn)
+            continue;
         await writeFile(join(versionDir, filename), filename === "tokens.css"
             ? theirVars.css
             : filename === "theme.css"
@@ -227,12 +259,35 @@ export async function add(slug, opts) {
                 : content, "utf8");
     }
     // 2. canonical source of truth
-    await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document, null, 2)}\n`, "utf8");
-    // 3. guide for the agent (generated client-side from the document)
-    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload), "utf8");
+    /**
+     * O DOCUMENTO FICA - ele É a referência que o agente dele lê (decisão do dono, 01/09) - E ELE VAI
+     * COMPACTO.
+     *
+     * MEDIDO em 01/09 no `codelevel`, 62 componentes: `null, 2` custa **347 400 bytes**; sem a
+     * indentação são **213 470** - 134 KB de espaço em branco, 39% do arquivo, num arquivo que
+     * NENHUM humano abre para ler. Quem o consome são `loadSystem` e as quatro ferramentas do MCP, e
+     * `JSON.parse` não distingue os dois.
+     *
+     * O que o cliente ganha: o mesmo dado, com 39% a menos de diff em todo `upgrade` e 134 KB a menos
+     * no repositório dele. Quem quiser lê-lo com os olhos tem `describe_component`, que responde por
+     * componente em vez de por arquivo.
+     */
+    await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document)}\n`, "utf8");
+    /**
+     * 3. O GUIA - e o catálogo só é COPIADO onde não há caminho de volta.
+     *
+     * Com o servidor MCP registrado, `list_components` e `describe_component` servem o mesmo catálogo
+     * por componente e sob demanda, então copiá-lo inteiro é peso e duplicação. MEDIDO em 01/09 no
+     * `codelevel`: 923 das 1225 linhas do guia (75%) eram o catálogo, num arquivo de 113 KB.
+     *
+     * É a MESMA pergunta que o manifesto do `CLAUDE.md` já faz desde 20/08, e por isso a MESMA
+     * função responde: cortar sem caminho de volta trocaria contexto por ignorância.
+     */
+    const tools = await recallAvailable(projectRoot);
+    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload, tools.available), "utf8");
     // 4. stable root re-exports for each CSS artifact → always the active version,
     //    so the consumer's @import path never changes across updates
-    const cssArtifacts = Object.keys(payload.artifacts).filter((f) => f.endsWith(".css"));
+    const cssArtifacts = Object.keys(payload.artifacts).filter((f) => f.endsWith(".css") && !(f === "shadcn.css" && !wantsShadcn));
     for (const filename of cssArtifacts) {
         await writeFile(join(slugDir, filename), `/* Active version (v${payload.version}). Managed by synthesisui - do not edit. */\n` +
             `@import "./v${payload.version}/${filename}";\n`, "utf8");
@@ -434,11 +489,34 @@ export async function add(slug, opts) {
         console.log(`↺ ${payload.name} active version set to v${v} (was v${prev.version})`);
     }
     const files = [
-        ...Object.keys(payload.artifacts),
+        ...Object.keys(payload.artifacts).filter((f) => !(f === "shadcn.css" && skipped)),
         "design-system.json",
         "GUIDE.md",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
+    /**
+     * O QUE NÃO FOI ESCRITO, DITO EM VOZ ALTA - lei 8, e ela vale nos dois sentidos.
+     *
+     * Deixar de plantar um arquivo é melhor que plantá-lo, mas fazê-lo em SILÊNCIO é como o produto
+     * ganha a fama de esconder coisas: alguém que já viu `shadcn.css` num outro repositório procuraria
+     * aqui e concluiria que a instalação falhou. A frase diz o que não veio, por quê, e o que muda a
+     * resposta.
+     */
+    if (skipped)
+        console.log(`  shadcn.css was not written: this repository has no \`components.json\`, so nothing here wears shadcn's variables. Add shadcn and run \`synthesisui add ${payload.slug}\` again to get the adapter.`);
+    /**
+     * O QUE FALTA PARA A PROMESSA DO `.gitignore` SER VERDADE - ver `tracksAnyOf`.
+     *
+     * O arquivo que a gente escreve dentro de `_synthesisui/` diz que a identidade e o CSS são
+     * commitados, e nenhum comando nunca verificou. MEDIDO em 01/09 no `codelevel`: zero arquivos
+     * rastreados depois de um `add` bem-sucedido.
+     *
+     * A frase lidera pelo EFEITO, porque é ele que faz alguém agir: "o build de um colega não tem
+     * tokens" move; "a pasta está untracked" não.
+     */
+    const tracked = await tracksAnyOf(projectRoot, `_synthesisui/ds/${payload.slug}`);
+    if (tracked === false)
+        console.log(`  none of this is in version control yet - a colleague who clones this repository gets no tokens, and their build breaks. \`git add _synthesisui/ds\` commits the identity and the CSS; the measurement and the local record are already ignored for you.`);
     /**
      * A FOLHA NÃO É A QUE O SERVIDOR COMPILOU, e calar isso é o pior dos dois mundos: o cliente vê um
      * `var(--color-ink-500)` num arquivo "gerenciado pelo synthesisui" e não tem como saber de onde
@@ -519,7 +597,16 @@ export async function add(slug, opts) {
     /** Nenhuma pasta encontrada: os caminhos viram exemplo, e o texto abaixo diz isso. */
     const appDir = appDirs[0] ?? projectConfig.pagesDir;
     const appDirFound = appDirs.length > 0;
-    const importPrefix = "../".repeat(appDir.split("/").length);
+    /**
+     * A FOLHA GLOBAL QUE ELE DE FATO CARREGA - ver `globalSheetOf`.
+     *
+     * A instrução mandava editar `<appDir>/globals.css`. MEDIDO em 01/09 no `codelevel`: os dois apps
+     * dele fazem `@import "@repo/ui/styles/globals.css"`, e o `globals.css` do app diz em comentário
+     * *"Do not redeclare tokens or fonts here"*. O arquivo certo era o do pacote, e a gente apontava
+     * para o do app - com o caminho relativo do app, que dali não resolve.
+     */
+    const sheet = await globalSheetOf(projectRoot, `${appDir}/globals.css`);
+    const importPrefix = prefixFrom(sheet);
     console.log(section("One-time setup (once per app)"));
     /**
      * "ONCE PER APP" É LITERAL NUM MONOREPO, e calar os outros apps entrega metade da fiação. Os
@@ -528,7 +615,9 @@ export async function add(slug, opts) {
      */
     if (appDirs.length > 1)
         console.log(line(`(${appDirs.length} apps here: ${appDirs.join(", ")} - the paths below are for ${appDir}; repeat for the others.)`));
-    console.log(line(`1. Import the system in your GLOBAL stylesheet, e.g. ${appDir}/globals.css`));
+    console.log(line(sheet === `${appDir}/globals.css`
+        ? `1. Import the system in your GLOBAL stylesheet, e.g. ${sheet}`
+        : `1. Import the system in ${sheet} - that is the sheet your apps load (${appDir}/globals.css only re-exports it, so tokens put there would not reach the package's own components):`));
     console.log(line(`   (the path is relative to that file - hence the leading ${importPrefix}):`));
     console.log("");
     // THE BRIDGE ONLY EXISTS FOR PEOPLE WHO ALREADY HAVE SHADCN, so it only
@@ -539,7 +628,8 @@ export async function add(slug, opts) {
     // can just build a design system with shadcn", with the answer sitting
     // unimported in his own repo. Naming it to everybody would be noise; naming it
     // to whoever has `components.json` is the whole feature arriving.
-    const hasShadcn = await access(join(projectRoot, "components.json")).then(() => true, () => false);
+    /** A MESMA pergunta que decide a ESCRITA - ver `wantsShadcn`. Duas leituras seriam duas regras. */
+    const hasShadcn = await wearsShadcn(projectRoot);
     console.log(snippet([
         ...(hasTheme ? [`@import "tailwindcss";`] : []),
         `@import "${importPrefix}_synthesisui/ds/${payload.slug}/tokens.css";`,

package/dist/commands/sync.js

@@ -21,6 +21,25 @@ import { resolveReadParts, siblingProjects, takeCensus, } from "./import.js";
  * after `closeRequest` runs here, so the person knows what happened and what
  * (if anything) is theirs to do next.
  */
+/**
+ * ONDE O SYNC FOI PARAR, E O QUE FALTA PARA CHEGAR NO DISCO DELE.
+ *
+ * O `sync` escreve no RASCUNHO, e o registry serve a última PUBLICADA - por lei, desde 29/07: se o
+ * rascunho fluísse para o repo, o botão Publish não seguraria nada. Então uma medição bem-sucedida
+ * termina com o repositório dele **inalterado**, e nada dizia isso.
+ *
+ * MEDIDO em 01/09 no `codelevel`: o `sync` escreveu 62 de 62 componentes na v4 (o rascunho, com 1276
+ * revisões), o `add` tinha instalado a v3 (a última publicada), e o output mandou o cliente para o
+ * Studio - uma tela, não o passo que falta.
+ *
+ * É A MESMA LIÇÃO DE 13/08, uma superfície adiante - ver `decisionLine`, caso `authored`. Lá, "Get
+ * it: upgrade" mandava rodar um comando que responde `already at the latest version`: a pessoa
+ * seguia a instrução, não recebia nada, e ficava sem saber se errou ou se a ferramenta falhou. A
+ * frase de lá nomeia os DOIS passos na ordem, e o primeiro é dele - esta faz o mesmo.
+ */
+export function draftLine(slug, base) {
+    return `this went into your DRAFT - your repository still has what you installed. It reaches the disk once you publish${base ? `: ${base}/dashboard/mine/${slug}/publish` : ""}\n      then: npx synthesisui@latest upgrade ${slug}`;
+}
 export function decisionLine(d, slug, 
 /** Onde o sistema dele vive - o `publish` mora lá, e sem o endereço a frase manda procurar. */
 base) {
@@ -563,6 +582,27 @@ export async function remeasure(args) {
         console.log(body(paint.strong(said)));
     if (out.url)
         console.log(body(out.url));
+    /**
+     * ONDE ISSO FOI PARAR, E O QUE FALTA PARA CHEGAR NO DISCO DELE.
+     *
+     * O `sync` escreve no RASCUNHO, e o registry serve a última PUBLICADA - por lei, desde 29/07: se o
+     * rascunho fluísse para o repo, o botão Publish não seguraria nada. Então uma medição bem-sucedida
+     * termina com o repositório dele **inalterado**, e nada dizia isso.
+     *
+     * MEDIDO em 01/09 no `codelevel`: o `sync` escreveu 62 de 62 componentes na v4 (o rascunho, com
+     * 1276 revisões), o `add` tinha instalado a v3 (a última publicada), e o output mandou o cliente
+     * para o Studio - uma tela, não o passo que falta.
+     *
+     * É A MESMA LIÇÃO DE 13/08, uma superfície adiante. Lá, `authored` dizia "Get it: upgrade" e o
+     * `upgrade` respondia `already at the latest version`: a pessoa seguia a instrução, não recebia
+     * nada, e ficava sem saber se errou ou se a ferramenta falhou. A frase de lá nomeia os DOIS passos
+     * na ordem, e o primeiro é dele - esta faz o mesmo.
+     *
+     * Só aparece quando algo FOI escrito: um `sync` que não mudou nada não tem o que publicar, e
+     * cobrar um publish vazio é o aviso que ensina a ignorar o próximo.
+     */
+    if ((out.written ?? 0) > 0)
+        console.log(body(paint.faint(draftLine(slug, base))));
     /**
      * O QUE MUDOU DESDE A ÚLTIMA VEZ - a linha que só uma RE-medição pode dar.
      *

package/dist/doctor/css-modules.js

@@ -202,7 +202,17 @@ function declarations(body) {
      */
     let flat = body;
     for (let guard = 0; guard < 12; guard++) {
-        const next = flat.replace(/\{[^{}]*\}/g, "");
+        /**
+         * O CABEÇALHO SAI JUNTO COM O BLOCO, e não depois - senão ele fica grudado na declaração
+         * seguinte e come a declaração inteira. Tirando só `{ … }`, o corpo de
+         *
+         *     .panel { color: red; &:hover { color: blue; } padding: 24px; }
+         *
+         * virava `color: red; &:hover  padding: 24px;`, e o pedaço do meio tem `:` no `:hover`:
+         * a propriedade lida era `&` e o `padding` do cartão dele MORRIA - a decisão estava no
+         * código, contada como interpretada, e não chegava à receita.
+         */
+        const next = flat.replace(/[^;{}]*\{[^{}]*\}/g, "");
         if (next === flat)
             break;
         flat = next;

package/dist/doctor/fragments.js

@@ -197,6 +197,48 @@ function backtick(source, from) {
  * contagem: um global com regra de CLASSE é forma que nenhum leitor cobre hoje - 399 declarações
  * no repo dele, e a única lacuna que estava calada em vez de declarada (04/08).
  */
+/**
+ * O SELETOR DE UMA DECLARAÇÃO, resolvido contra os blocos que a contêm.
+ *
+ * O QUE O CLIENTE GANHA: uma declaração que ele escreveu dentro de `&:hover` chega aqui como
+ * `.card:hover` - o nome inteiro, o mesmo que o navegador aplica. Sem isto ela chegava como
+ * `&:hover`, e um `&` sem pai não tem a quem se ligar: nenhum leitor deste lado ou do outro
+ * consegue dizer de que elemento aquela decisão é.
+ *
+ * UMA AT-RULE É CONTEXTO, NUNCA PAI. `@media (…) { .card { padding } }` é uma decisão do `.card`
+ * sob uma condição, e não de um elemento chamado `@media`. A at-rule só responde pelo seletor
+ * quando não há nenhum dentro dela - que é como `@utility text-grad { … }` do Tailwind 4 e o
+ * `0%` de um `@keyframes` seguem chegando exatamente como chegavam.
+ */
+function selectorOf(open) {
+    let selector = "";
+    let atRule = "";
+    for (const block of open) {
+        if (!block)
+            continue;
+        if (block.startsWith("@")) {
+            if (!selector)
+                atRule = block;
+            continue;
+        }
+        selector = selector ? resolveNesting(block, selector) : block;
+    }
+    return selector || atRule;
+}
+/**
+ * O `&` DO FILHO TROCADO PELO PAI, e o filho sem `&` pendurado como descendente - as duas
+ * regras do CSS aninhado. Uma lista de pais vira `:is(a, b)`, que é o que o próprio CSS faz:
+ * escrever `a, b:hover` diria outra coisa, e diria errado.
+ */
+function resolveNesting(child, parent) {
+    const base = parent.includes(",") ? `:is(${parent})` : parent;
+    return child
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => part.includes("&") ? part.replaceAll("&", base) : `${base} ${part}`)
+        .join(", ");
+}
 export function fragmentsOfStylesheet(file, css, 
 /**
  * COMO ESTA FOLHA CHEGA NO BUILD DELES, e isso vem do GRAFO DE IMPORTS e nunca do nome do
@@ -212,31 +254,54 @@ export function fragmentsOfStylesheet(file, css,
  */
 kind) {
     const out = [];
-    let selector = "";
+    /**
+     * OS BLOCOS ABERTOS, E NÃO O ÚLTIMO SELETOR VISTO.
+     *
+     * O QUE O CLIENTE VIVIA COM UMA VARIÁVEL SÓ: depois de um bloco aninhado, TODA declaração que
+     * vinha a seguir ficava com o seletor do bloco que já tinha fechado. No `.card { color: red;
+     * &:hover { color: blue } padding: 8px }`, o `padding` dele era registrado como sendo do
+     * `:hover` - uma decisão de repouso lida como decisão de estado. Medido no repositório vivo em
+     * 01/09, sobre 724 folhas e 19 374 declarações: **440 (2,3%) ficavam com o seletor de um bloco
+     * já fechado, e 942 (4,9%) saíam com um `&` que não tinha pai a que se referir**.
+     */
+    const open = [];
     for (const [i, raw] of css.split("\n").entries()) {
         const line = raw.replace(/\/\*.*?\*\//g, "");
         for (const piece of line.matchAll(PIECES)) {
             const text = (piece[1] ?? "").trim();
             if (piece[2] === "{") {
-                selector = text;
+                open.push(text);
                 continue;
             }
+            /**
+             * O BLOCO SÓ FECHA DEPOIS QUE A DECLARAÇÃO DELE FOI LIDA. `.a { color: red }` numa linha
+             * só termina a declaração no `}`, sem `;` - desempilhar antes de ler perdia a última
+             * declaração de todo bloco escrito assim. Medido no repositório vivo quando aconteceu:
+             * 19 declarações a menos no censo do `frontend-hub`, num conserto que só devia mexer em
+             * QUAL seletor cada uma tem.
+             */
+            const closes = piece[2] === "}";
             /**
              * Sem terminador não há declaração: `padding: 8px` no fim de uma linha pode ser a primeira
              * metade de um valor que continua na próxima.
              */
-            if (!piece[2] || !text)
+            if (!piece[2] || !text) {
+                if (closes)
+                    open.pop();
                 continue;
+            }
             const m = DECLARATION.exec(text);
-            if (!m)
-                continue;
             /**
              * UM TOKEN NÃO É UM FRAGMENTO DE COMPONENTE. `--color-ocean-500: #…` é a paleta, e ela tem
              * o seu próprio caminho e o seu próprio relatório; contá-la aqui inflaria o total com o que
              * já está coberto em outro lugar.
              */
-            if (m[1].startsWith("--"))
+            if (!m || m[1].startsWith("--")) {
+                if (closes)
+                    open.pop();
                 continue;
+            }
+            const selector = selectorOf(open);
             out.push({
                 shape: "css",
                 file,
@@ -249,6 +314,8 @@ kind) {
                         ? { reason: "sheet-not-imported" }
                         : {}),
             });
+            if (closes)
+                open.pop();
         }
     }
     return out;
@@ -302,6 +369,24 @@ const STRUCTURE = new Set([
 function targetClass(text) {
     const brace = text.indexOf("{");
     const selector = brace === -1 ? text : text.slice(0, brace);
+    /**
+     * `@utility x` É A CLASSE `.x` - ela é a forma do Tailwind 4 de declarar um utilitário, e não
+     * traz o ponto que este casamento procura.
+     *
+     * O QUE ELE VIA SEM ISTO: a declaração CHEGAVA ao componente e o relatório dizia que não. O
+     * `readGlobalClasses` lê `@utility` desde 24/08 e a entrega no look de quem veste a classe -
+     * medido em 01/09 pela cadeia real, o `Scene` recebe `perspective: 900px` da `@utility
+     * scene-3d`. Mas o julgamento procurava um ponto no seletor, não achava, e mandava as mesmas
+     * declarações para o ledger como forma sem leitor. No censo do `codelevel`: **68 declarações
+     * em 22 utilities anunciadas como não interpretadas**, com as duas que um componente veste
+     * (`scene-3d` no `Scene`, `stage-3d` no `Stage`) já dentro da receita dele.
+     *
+     * Um número que acusa lacuna onde não há custa o mesmo que um que a esconde: manda alguém
+     * consertar o que não está quebrado. Quase custou um leitor inteiro escrito duas vezes.
+     */
+    const utility = /^@utility\s+([a-z][\w-]*)/i.exec(selector.trim())?.[1];
+    if (utility)
+        return utility;
     for (const group of selector.split(",")) {
         const classes = group.match(/\.[A-Za-z][\w-]*/g);
         /** Sem o ponto: o nome que `globalClasses` indexa. */

package/dist/global-sheet.js

@@ -0,0 +1,103 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, posix, relative, resolve } from "node:path";
+/**
+ * A FOLHA GLOBAL QUE OS APPS DELE REALMENTE CARREGAM - e num monorepo ela quase nunca é a do app.
+ *
+ * O QUE O CLIENTE PERCEBE SEM ISTO. O `add` manda importar os tokens em `apps/<x>/app/globals.css`.
+ * MEDIDO em 01/09 no `codelevel`: os DOIS apps dele fazem `@import "@repo/ui/styles/globals.css"`, e
+ * o `globals.css` do app diz, em comentário dele, *"Do not redeclare tokens or fonts here - extend in
+ * styles/"*. A instrução apontava para o arquivo errado, e a convenção certa estava escrita ali do
+ * lado.
+ *
+ * Ele seguiu a instrução no arquivo CERTO - o do pacote - e o caminho relativo que a gente imprimiu
+ * era o do app. Um monorepo com pacote de UI compartilhado não é exceção: é a forma comum, e a
+ * instrução tem que derivar de onde o CSS dele mora em vez de assumir.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * COMO A FOLHA REAL É ENCONTRADA, e nada aqui é palpite:
+ *
+ *     1. abre o `globals.css` do app
+ *     2. procura `@import "<spec>"` que aponte para um CSS DENTRO deste repositório
+ *     3. resolve o `<spec>`: caminho relativo, ou pacote do workspace pelo `exports`
+ *     4. repete na folha encontrada, até ela não re-exportar mais
+ *
+ * O QUE NÃO É SEGUIDO: `tailwindcss` e qualquer coisa que não resolva para um arquivo daqui. Um
+ * `@import "tailwindcss"` é a biblioteca, e mandar o cliente editá-la seria pior que a instrução que
+ * isto conserta.
+ */
+/** Quantos saltos seguir antes de desistir - um ciclo de imports não pode travar um `add`. */
+const MAX_HOPS = 5;
+const IMPORT = /@import\s+["']([^"']+)["']/g;
+/** `@repo/ui/styles/globals.css` → `packages/ui/src/styles/globals.css`, pelo `exports` dele. */
+async function fromWorkspace(root, spec) {
+    for (const group of ["packages", "apps", "libs"]) {
+        let entries;
+        try {
+            const { readdir } = await import("node:fs/promises");
+            entries = await readdir(join(root, group));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const pkgPath = join(root, group, entry, "package.json");
+            const raw = await readFile(pkgPath, "utf8").catch(() => null);
+            if (!raw)
+                continue;
+            let pkg;
+            try {
+                pkg = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (!pkg.name || !spec.startsWith(`${pkg.name}/`))
+                continue;
+            const sub = `./${spec.slice(pkg.name.length + 1)}`;
+            const target = pkg.exports?.[sub];
+            if (typeof target !== "string")
+                continue;
+            return posix.join(group, entry, target.replace(/^\.\//, ""));
+        }
+    }
+    return null;
+}
+/**
+ * A folha onde os tokens dele devem entrar, relativa à raiz - `appSheet` quando nada a re-exporta.
+ */
+export async function globalSheetOf(root, appSheet) {
+    let current = appSheet;
+    for (let hop = 0; hop < MAX_HOPS; hop += 1) {
+        const raw = await readFile(join(root, current), "utf8").catch(() => null);
+        if (!raw)
+            return current;
+        let next = null;
+        for (const m of raw.matchAll(IMPORT)) {
+            const spec = m[1];
+            if (!spec.endsWith(".css"))
+                continue;
+            const candidate = spec.startsWith(".")
+                ? posix.normalize(posix.join(posix.dirname(current), spec))
+                : await fromWorkspace(root, spec);
+            if (!candidate)
+                continue;
+            /** Fora da raiz não é folha dele para editar - e um `..` demais sai do repositório. */
+            if (candidate.startsWith(".."))
+                continue;
+            const readable = await readFile(join(root, candidate), "utf8").catch(() => null);
+            if (readable === null)
+                continue;
+            next = candidate;
+            break;
+        }
+        if (!next || next === current)
+            return current;
+        current = next;
+    }
+    return current;
+}
+/** O `../` que leva daquela folha até a raiz do repositório - o prefixo do `@import`. */
+export function prefixFrom(sheet) {
+    const up = relative(dirname(resolve("/r", sheet)), "/r");
+    return up === "" ? "./" : `${up.split(/[\\/]/).join("/")}/`;
+}

package/dist/guide.js

@@ -244,7 +244,42 @@ function componentEntry(cname, recipe) {
  * components with claude-code" work: the tokens alone are not enough, the agent
  * needs the rules and the real vocabulary (semantic token names and recipes).
  */
-export function buildGuide(payload) {
+/**
+ * O QUE FICA NO LUGAR DO CATÁLOGO - e ele diz QUANTOS existem, nunca só que existem.
+ *
+ * Um guia que omite o catálogo em silêncio ensina o agente que o sistema não tem componente nenhum,
+ * que é o oposto do que ele precisa saber antes de escrever a primeira tela.
+ */
+function toolsPointer(count) {
+    return `This system defines **${count} component${count === 1 ? "" : "s"}**, and they are NOT listed here on purpose: the tools answer the same
+question with the piece you actually need, at the moment you need it.
+
+- \`list_components\` - every name, with what each one is for. Call it BEFORE writing any UI
+  element from scratch; if one covers the purpose, use it instead of inventing another.
+- \`describe_component { name }\` - one component in full: its parts, its axes, the libraries it
+  needs, and the rules that govern it.
+- \`add_blueprint { name }\` - the same component as typed code in your repository.
+
+A name alone does not tell you that an editor needs \`@tiptap/react\`, or that a card is built out
+of a metric card - so read the component before you use it, never the list alone.`;
+}
+export function buildGuide(payload, 
+/**
+ * AS FERRAMENTAS ESTÃO AO ALCANCE DESTE REPOSITÓRIO? - ver `recallAvailable`.
+ *
+ * O QUE O CLIENTE GANHA. O catálogo inteiro deixa de ser copiado para o disco dele quando existe
+ * caminho de volta: `list_components` e `describe_component` servem a MESMA coisa, por componente
+ * e no momento em que o agente precisa. MEDIDO em 01/09 no `codelevel`: a seção do catálogo é
+ * **923 de 1225 linhas do guia (75%)**, e o arquivo inteiro pesa 113 KB no repositório dele.
+ *
+ * POR QUE É A MESMA RÉGUA DO MANIFESTO. O corte de 20/08 (`readManifest`) já usa exatamente este
+ * sinal, pelo mesmo motivo: cortar sem caminho de volta troca contexto por ignorância. Aqui a
+ * pergunta é idêntica, e por isso a resposta vem de fora - quem sabe é quem leu o `.mcp.json`.
+ *
+ * `false` mantém o guia inteiro, que é o comportamento de todo repositório sem o servidor
+ * registrado.
+ */
+toolsReachable = false) {
     const { document: doc, slug, name, version } = payload;
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
@@ -360,6 +395,21 @@ ${depLines.join("\n")}
     const hasTailwind = "theme.css" in payload.artifacts;
     const hasParts = Object.values(components).some((r) => r.parts && Object.keys(r.parts).length > 0);
     const componentLines = Object.entries(components).map(([cname, recipe]) => componentEntry(cname, recipe));
+    /**
+     * O CORTE SÓ ACONTECE QUANDO ELE DE FATO CORTA - e este é o único jeito honesto de prometê-lo.
+     *
+     * O ponteiro para as ferramentas tem tamanho fixo. Num sistema de três componentes com descrições
+     * de uma linha, ele é MAIOR que o catálogo que substitui - e um guia que cresceu não pode ser
+     * anunciado como dieta de contexto. MEDIDO em 01/09: no `codelevel`, com 62 componentes, o corte é
+     * de 82% (114 431 -> 20 425 bytes); numa fixture de 3, o ponteiro custaria 7% a mais.
+     *
+     * Comparar os dois textos responde sozinho, em todo tamanho de sistema, sem limiar escrito à mão
+     * que envelheceria no dia em que o ponteiro mudasse de tamanho. Há 4 sistemas de 2 componentes em
+     * produção, e para eles copiar continua sendo o mais barato.
+     */
+    const catalogueText = componentLines.join("\n\n");
+    const pointerText = toolsPointer(componentLines.length);
+    const pointerBeatsCatalogue = pointerText.length < catalogueText.length;
     // Motion vocabulary: the system's keyframes, named and usable. Intent is
     // classified from the frames (same logic that compiled the animate-*
     // utilities into theme.css), so what this section PROMISES about a utility's
@@ -742,7 +792,7 @@ Each recipe becomes a \`.ds-<name>\` class (inside the \`[data-ds="${slug}"]\` s
 \`data-<axis>="<option>"\` attributes; states (hover/focus/active/disabled) ship in the CSS;
 multi-part components expose \`.ds-<name>-<part>\` classes (listed under each).
 
-${componentLines.join("\n\n")}
+${toolsReachable && pointerBeatsCatalogue ? pointerText : catalogueText}
 ${blockEntries.length
         ? `
 ---
@@ -760,6 +810,9 @@ ${blockLines.join("\n\n")}
         : ""}
 ---
 
-_Full canonical source of truth (including values and keyframes) in \`design-system.json\`._
+_Full canonical source of truth (including values and keyframes) in \`design-system.json\`._${toolsReachable && pointerBeatsCatalogue
+        ? `
+_The component catalogue is served by the tools rather than copied here - see the section above._`
+        : ""}
 `;
 }

package/dist/install-marks.js

@@ -152,7 +152,7 @@
  * comentou vinha sendo escrito na pasta dele como componente de verdade. Medido em 14 arquivos
  * das duas populações o nó fantasma era a RAIZ - o elemento cujas classes viram a `base`.
  */
-export const MATERIALISER_SINCE = "0.16.345";
+export const MATERIALISER_SINCE = "0.16.349";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -532,7 +532,7 @@ export const CHECKER_SINCE = "0.16.308";
  * si, o campo fica ausente, e ausente ali continua sendo a resposta certa - o `codelevel-ui` dá
  * 0 de 0 contra 145 arquivos de página do `frontend-hub`.
  */
-export const READER_SINCE = "0.16.346";
+export const READER_SINCE = "0.16.348";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/tracked.js

@@ -0,0 +1,40 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/**
+ * ESTES ARQUIVOS ESTÃO NO CONTROLE DE VERSÃO DELE? - e a resposta muda o que o `add` diz no fim.
+ *
+ * O QUE O CLIENTE PERCEBE SEM ISTO. O `.gitignore` que NÓS geramos dentro de `_synthesisui/` promete,
+ * em comentário: *"a identidade e o CSS são commitados para que um clone fresco seja governado"*. Ele
+ * lista o que NÃO versionar, e daí em diante todo mundo assume que o resto está versionado. Ninguém
+ * nunca fez o `git add`, e nenhum comando checou.
+ *
+ * MEDIDO em 01/09 no `codelevel`, depois de um `add` bem-sucedido: `git ls-files _synthesisui/`
+ * devolve **0 arquivos**, e o status mostra `?? _synthesisui/`. A promessa não se cumpria em lugar
+ * nenhum, e o custo apareceu no mesmo dia - o dono apagou a pasta, ela não voltou do `git checkout`,
+ * e ele precisou de um `add` para recuperá-la. Um colega clonando o repositório teria um build sem
+ * tokens.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * LEITURA, NUNCA ESCRITA - e isso não é cautela, é o contrato.
+ *
+ * Rodar `git add` por conta própria mexeria no index dele: alguém no meio de um commit parcial
+ * encontraria arquivos nossos na área de stage sem ter pedido. O produto DIZ o que falta e por quê;
+ * quem versiona o repositório é ele.
+ *
+ * E ela CALA quando não sabe: fora de um repositório git, ou sem o binário, a pergunta não tem
+ * resposta - e um aviso sobre versionamento num diretório que não é versionado seria ruído puro.
+ */
+export async function tracksAnyOf(root, path) {
+    try {
+        const { stdout } = await run("git", ["ls-files", "--", path], {
+            cwd: root,
+            timeout: 5000,
+        });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        /** Não é repositório git, ou o git não está aqui: sem resposta, sem aviso. */
+        return null;
+    }
+}

package/package.json

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