synthesisui 0.16.348 → 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/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.
  *

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.348",
+  "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": {