synthesisui 0.16.348 → 0.16.351

package/dist/census-pages.js

@@ -0,0 +1,66 @@
+/**
+ * COMO ELE MONTA UMA PÁGINA - a régua única, num módulo só.
+ *
+ * O que o cliente ganha: o planejador de página oferece o esqueleto que ELE já usa - as peças
+ * dele, na ordem em que ele as escreve - em vez dos três layouts que NÓS escrevemos. Ver
+ * `INV-COLETA-12` em `contracts/camada-1-coleta.md`.
+ *
+ * POR QUE ISTO NÃO MORA EM `import.ts`: três lugares precisam da mesma resposta - a varredura do
+ * escopo, a varredura da evidência (`--usage`, que é onde as páginas moram em todo monorepo) e a
+ * FUSÃO de dois escopos medidos. Duas cópias da transcrição seriam duas réguas no dia em que uma
+ * fosse editada, e o teto declarado num arquivo e furado no outro seria um teto que não existe.
+ */
+import { sketchOf } from "./doctor/sketch.js";
+import { transcribe } from "./doctor/transcribe.js";
+/**
+ * QUANTAS PÁGINAS VIAJAM NO CENSO.
+ *
+ * O teto existe pela mesma razão que o de `skipped`: num monorepo o número estoura e o censo
+ * viraria um dump do repositório. Medido em 01/09, o `frontend-hub` tem 145 arquivos de página e
+ * o nosso app 65, então 400 cabe as duas populações inteiras e o corte só aparece em repositório
+ * bem maior que os que a gente mede.
+ *
+ * E QUANDO ELE CORTAR, `pagesTotal` diz quantas eram. Uma tela que contasse `pages.length` diria
+ * 400 e pareceria completa, que é a forma mais barata de um corte silencioso mentir.
+ */
+export const PAGES_MAX = 400;
+/**
+ * UMA PÁGINA DELE, TRANSCRITA - a moldura da raiz e as peças que ela compõe.
+ *
+ * `from` VEM DO SKETCH e não de uma segunda leitura do arquivo: o nó já carrega o especificador
+ * que o import dele declara, e reabrir o arquivo para descobrir o mesmo fato é a falha de
+ * esteira que o dono nomeou em 01/08.
+ */
+export function pageCompositionOf(rel, src, name, declaredValues) {
+    const sketch = sketchOf(src, name);
+    const at = sketch[0];
+    return {
+        file: rel,
+        root: at?.classes
+            ? transcribe(at.classes.split(/\s+/).filter(Boolean), declaredValues).base
+            : {},
+        composes: sketch
+            .filter((n) => /^[A-Z]/.test(n.tag))
+            .map((n) => ({
+            name: n.tag.split(".")[0],
+            ...(n.from ? { from: n.from } : {}),
+            depth: n.depth,
+        })),
+    };
+}
+/**
+ * AS PÁGINAS DE DOIS ESCOPOS MEDIDOS, SOMADAS - e o teto reaplicado sobre a soma.
+ *
+ * Cada escopo mediu arquivos DIFERENTES, então isto é soma e não desempate: nenhuma regra do
+ * primeiro-escopo-vence se aplica a um conjunto disjunto. O que se preserva é o denominador -
+ * `pagesTotal` conta quantas foram VISTAS em cada medição, inclusive as que aquela medição já
+ * havia cortado, senão a soma de dois cortes leria como o total do projeto.
+ */
+export function mergePages(list) {
+    const all = list.flatMap((c) => c.pages ?? []);
+    if (all.length === 0)
+        return {};
+    const seen = list.reduce((n, c) => n + (c.pagesTotal ?? (c.pages ?? []).length), 0);
+    const pages = all.slice(0, PAGES_MAX);
+    return { pages, ...(seen > pages.length ? { pagesTotal: seen } : {}) };
+}

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

@@ -3,6 +3,7 @@ import { basename, dirname, join, relative, sep } from "node:path";
 import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { applyAnatomyPatch, hasEdits, } from "../anatomy-patch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
+import { PAGES_MAX, pageCompositionOf } from "../census-pages.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
 import { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, packagingOf, proposeNewHome, resolvesAs, } from "../doctor/architecture.js";
@@ -68,17 +69,12 @@ import { walk, walkAll } from "./doctor.js";
  * nunca o nome do arquivo - e é isso que a faz valer no projeto de alguém que a gente nunca viu.
  */
 /**
- * QUANTAS PÁGINAS VIAJAM NO CENSO.
+ * O TETO DE PÁGINAS, re-exportado de onde a régua inteira mora - ver `census-pages.ts`.
  *
- * O teto existe pela mesma razão que o de `skipped`: num monorepo o número estoura e o censo
- * viraria um dump do repositório. Medido em 01/09, o `frontend-hub` tem 145 arquivos de página e
- * o nosso app 65, então 400 cabe as duas populações inteiras e o corte só aparece em repositório
- * bem maior que os que a gente mede.
- *
- * E QUANDO ELE CORTAR, `pagesTotal` diz quantas eram. Uma tela que contasse `pages.length` diria
- * 400 e pareceria completa, que é a forma mais barata de um corte silencioso mentir.
+ * Ele vive lá porque a FUSÃO de dois escopos precisa reaplicá-lo sobre a soma, e um teto
+ * declarado num arquivo e furado no outro é um teto que não existe.
  */
-export const PAGES_MAX = 400;
+export { PAGES_MAX };
 /**
  * How many distinct values travel, PER KIND.
  *
@@ -770,26 +766,7 @@ export async function takeCensus(root, opts) {
                  * que falta para alguém escrever a próxima (04/08).
                  */
                 if (verdict.why === "route" || verdict.why === "screen") {
-                    const sketch = sketchOf(src, d.name);
-                    const root = sketch[0];
-                    pages.push({
-                        file: rel,
-                        root: root?.classes
-                            ? transcribe(root.classes.split(/\s+/).filter(Boolean), declaredValues).base
-                            : {},
-                        /**
-                         * `from` VEM DO SKETCH e não de uma segunda leitura do arquivo: o nó já carrega o
-                         * especificador que o import dele declara, e reabrir o arquivo para descobrir o
-                         * mesmo fato é a falha de esteira que o dono nomeou em 01/08.
-                         */
-                        composes: sketch
-                            .filter((n) => /^[A-Z]/.test(n.tag))
-                            .map((n) => ({
-                            name: n.tag.split(".")[0],
-                            ...(n.from ? { from: n.from } : {}),
-                            depth: n.depth,
-                        })),
-                    });
+                    pages.push(pageCompositionOf(rel, src, d.name, declaredValues));
                 }
                 skips.push({
                     name: d.name,
@@ -1456,6 +1433,11 @@ export async function takeCensus(root, opts) {
      * not `reports`: an app's classes are choices made from a scale, and folding
      * them into the census would put the average back where the declaration goes.
      *
+     * A ÚNICA COISA QUE ESTE LAÇO ESCREVE ALÉM DA CONTAGEM É `pages`, e a razão é que uma página
+     * não é uma escolha de estilo: é a COMPOSIÇÃO dela - quais peças, em que ordem, sob que
+     * moldura. Ela não entra em `defined`, não declara token e não vota em escala. Ver o bloco
+     * `AS PÁGINAS MORAM AQUI` mais abaixo, com o número das duas populações.
+     *
      * Deliberately its own tally so the LIBRARY QUESTION is asked of the scope
      * alone. Fold the app in first and every export has a count, `isLibrary` reads
      * false, and the crosswalk starts substituting the components it was just
@@ -1548,6 +1530,41 @@ export async function takeCensus(root, opts) {
             // source - so measuring nesting only on the defined loop reported zero
             // companions on a 128-component library (e2e, 01/08).
             readNesting(rel, src, nesting);
+            /**
+             * AS PÁGINAS MORAM AQUI, E ATÉ AGORA O CENSO NÃO GUARDAVA NENHUMA.
+             *
+             * `Census.pages` é como ELE monta uma tela - a moldura da raiz e a ordem das peças -, e é
+             * o único dado a partir do qual alguém escreve a próxima página no vocabulário dele. Ele
+             * só era colhido na varredura do ESCOPO, e o escopo é a biblioteca: uma `packages/ui` não
+             * tem `app/` nem `pages/`, então a resposta era sempre zero. Medido em 01/09 nas duas
+             * populações, com o mesmo `--scope`/`--usage` que o `import` e o `sync` passam:
+             *
+             *     codelevel      0 páginas guardadas · 9 existem  (apps/web 3, apps/landing 6)
+             *     frontend-hub   0 páginas guardadas · 156 existem (apps/web-dashboard)
+             *
+             * Isto NÃO afrouxa a lei da passagem de evidência. Uma página não entra em `defined`, não
+             * doa token e não vota em escala: o que ela doa é COMPOSIÇÃO - quais peças dele seguram
+             * quais telas -, que é exatamente a classe de fato que `--usage` existe para trazer.
+             *
+             * A régua é a mesma do escopo, de propósito: o portão recusa a rota (`route`/`screen`) e
+             * é essa recusa que a identifica como página. Só o que o portão RECUSA por ser tela vira
+             * página, então nada que já é componente é contado duas vezes.
+             */
+            if (/\.(tsx|jsx)$/i.test(rel)) {
+                for (const d of scanDefinitions(rel, src)) {
+                    const verdict = gateComponent({
+                        name: d.name,
+                        file: rel,
+                        source: src,
+                        internal: [...shared, ...uInternal],
+                    });
+                    if (verdict.ok)
+                        continue;
+                    if (verdict.why !== "route" && verdict.why !== "screen")
+                        continue;
+                    pages.push(pageCompositionOf(rel, src, d.name, declaredValues));
+                }
+            }
             // Which PROJECT composes it - the credibility panel's number, per root.
             for (const m of src.matchAll(/<([A-Z][A-Za-z0-9_]*)/g)) {
                 const at = projectsOf.get(m[1]) ?? new Set();
@@ -2000,6 +2017,21 @@ export async function takeCensus(root, opts) {
         ]),
         islandRead: islandClassesRead,
         refused: new Set(skips.map((s) => s.file)),
+        /**
+         * AS ANIMAÇÕES QUE O CENSO CAPTUROU - ver o veredito em `judgeFragments`.
+         *
+         * `keyframes` é o objeto que já viaja no censo e que o compilador emite. Um frame de uma
+         * delas chegou por essa porta, então cobrá-lo como lacuna conta a mesma coisa duas vezes.
+         * A LISTA É A MESMA FUSÃO QUE O CENSO GRAVA, e não a metade de componente.
+         *
+         * `keyframes` sozinho é o que os componentes declaram; `globalKeyframes` é a folha dele, e
+         * é ali que os 35 do codelevel moram - o censo funde os dois na hora de escrever. Ler só o
+         * primeiro aqui declarava capturado um conjunto VAZIO e o conserto não movia nada: a
+         * primeira medição depois de ligar isto deu exatamente os mesmos 130 de antes.
+         *
+         * Se a captura falhar, o frame volta a ser lacuna sozinho, que é a resposta certa.
+         */
+        keyframes: new Set(Object.keys({ ...globalKeyframes, ...keyframes })),
     }, 
     /**
      * AS FORMAS QUE ELE DECLAROU - e é aqui que a declaração dele muda o veredito.

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

@@ -302,12 +302,24 @@ kind) {
                 continue;
             }
             const selector = selectorOf(open);
+            /**
+             * DE QUAL ANIMAÇÃO ESTE FRAME É - ver `Fragment.inKeyframe`.
+             *
+             * `selectorOf` devolve `0%`, porque o bloco do frame é um seletor comum e o at-rule só
+             * vence quando não há nenhum. O nome fica na pilha e é a única coisa que liga esta
+             * declaração ao keyframe que o censo capturou.
+             */
+            const inKeyframe = open
+                .map((b) => /^@keyframes\s+([^\s{]+)/.exec(b)?.[1])
+                .filter(Boolean)
+                .pop();
             out.push({
                 shape: "css",
                 file,
                 line: i + 1,
                 text: `${selector ? `${selector} ` : ""}{ ${m[1]}: ${m[2].trim()} }`,
                 read: false,
+                ...(inKeyframe ? { inKeyframe } : {}),
                 ...(kind === "global"
                     ? { reason: "shape-not-read" }
                     : kind === "dead"
@@ -440,7 +452,30 @@ forms = []) {
     const wornGlobal = elsewhere?.wornGlobal ?? new Set();
     const islandRead = elsewhere?.islandRead ?? new Map();
     const refused = elsewhere?.refused ?? new Set();
+    const captured = elsewhere?.keyframes ?? new Set();
     return seen.map((f) => {
+        /**
+         * UM FRAME DE UM KEYFRAME CAPTURADO CHEGOU - a mesma família de `wornGlobal` logo abaixo, e a
+         * mesma família de `INV-INTERP-15`: a régua acusava um fato que já estava no censo.
+         *
+         * `0% { opacity: 0 }` não tem leitor de RECEITA e nunca vai ter - um frame não é a decisão de
+         * um componente, é um instante de uma animação. Mas a animação inteira viaja em
+         * `census.keyframes`, com todos os seus frames, e o compilador a emite. Cobrar o frame como
+         * lacuna é contar duas vezes a mesma coisa e chamar a segunda de perda.
+         *
+         * MEDIDO EM 02/09, nas duas populações e com o mesmo `--scope`/`--usage` do produto:
+         *
+         *     codelevel      35 keyframes capturados · 87 de 105 declarações sem leitor eram frames (83%)
+         *     frontend-hub    1 keyframe  capturado ·  0 de   6 eram frames (0%)
+         *
+         * As duas discordam por larga margem, e é isso que decide o desenho: a pergunta não é sobre
+         * volume, é sobre a porta por onde a declaração passou. O nome tem que estar CAPTURADO - um
+         * frame de uma animação que o censo não colheu continua sendo lacuna, porque ali ela é real.
+         */
+        if (f.inKeyframe && captured.has(f.inKeyframe)) {
+            const { reason: _unread, ...rest } = f;
+            return { ...rest, read: true };
+        }
         /**
          * A REGRA DE CLASSE GLOBAL QUE ALGUÉM VESTE FOI LIDA - antes do desvio de
          * `binding`, porque lida é mais forte que ligada. `.root { isolation: isolate }`

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,42 @@ 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.348";
+/**
+ * 0.16.349 -> 0.16.350 em 01/09 (`INV-COLETA-12`, a metade do MONOREPO): as páginas do app dele
+ * passam a chegar ao censo mesmo quando a leitura foi apontada para a biblioteca.
+ *
+ * O QUE ELE GANHA COM O `sync`: a linha *"N of your components hold up M pages"* - quais peças
+ * dele são a espinha das telas dele. Quem roda `--scope packages/ui --usage apps/web` recebia
+ * ZERO página e o relatório calava as duas seções que falam delas.
+ *
+ * A CORREÇÃO DE UMA FRASE QUE ESTAVA AQUI: "ausente continua sendo a resposta certa para quem
+ * apontou a leitura para uma biblioteca" só valia para quem NÃO passou `--usage`. As páginas
+ * moram no app, e a varredura da evidência lia cada um desses arquivos para contagem e lei e
+ * passava direto pela composição. Medido em 01/09, com o mesmo `--scope`/`--usage` que o
+ * `import` e o `sync` passam:
+ *
+ *     codelevel      0 páginas guardadas · 9 existem  (apps/web 3, apps/landing 6)
+ *     frontend-hub   0 páginas guardadas · 156 existem (apps/web-dashboard)
+ *
+ * QUEM NÃO É AFETADO: quem mede um app inteiro sem escopo - esse caminho já carregava as páginas
+ * desde 0.16.348. E quem aponta para uma biblioteca sem `--usage`: ela não compõe telas dentro de
+ * si, o campo segue ausente, e ali a ausência é a resposta certa de verdade.
+ */
+/**
+ * 0.16.350 -> 0.16.351 em 02/09 (`INV-COLETA-16`): um frame de uma animação que o censo CAPTUROU
+ * deixa de ser contado como declaração sem leitor.
+ *
+ * O QUE ELE GANHA COM O `sync`: o número de cobertura para de contar como perdido o que a
+ * plataforma leu inteiro. `0% { opacity: 0 }` nunca vai ter leitor de RECEITA - um frame não é a
+ * decisão de um componente -, mas a animação viaja em `census.keyframes` e o compilador a emite.
+ *
+ *     codelevel      35 keyframes capturados · shape-not-read 130 -> 18 · CSS lido 35% -> 88%
+ *     frontend-hub    1 keyframe  capturado · shape-not-read   6 ->  6 · nada muda
+ *
+ * QUEM NÃO É AFETADO: quem não escreve `@keyframes`. E quem escreve um que a captura NÃO alcançou -
+ * ali o frame continua sendo lacuna, porque ali a perda é real.
+ */
+export const READER_SINCE = "0.16.351";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/merge-census.js

@@ -1,3 +1,4 @@
+import { mergePages } from "./census-pages.js";
 import { gapReason } from "./doctor/architecture.js";
 const asRecord = (v) => (v ?? {});
 /** Nome do escopo para as mensagens - `.` quando a medição não escopou nada. */
@@ -296,6 +297,25 @@ export function mergeCensus(list) {
         out.conventions = conventions;
     if (architectures && architectures.length > 0)
         out.architectures = architectures;
+    /**
+     * AS PÁGINAS DOS ESCOPOS SOMAM - ver `mergePages` em `census-pages.ts`.
+     *
+     * `out` nasce de um spread do PRIMEIRO censo e depois é montado campo a campo, então `pages`
+     * do primeiro escopo viajava de carona e a dos SEGUINTES caía inteira, sem uma linha dizendo
+     * isso. Com um escopo só o defeito não aparece (a fusão de uma lista devolve o próprio censo),
+     * e é por isso que ele sobreviveu: o caminho que o expõe é `--scope A --scope B`, que existe
+     * justamente para o sistema que mora em dois pacotes.
+     *
+     * `pagesTotal` também precisava ser recontado: herdado do primeiro, ele descrevia uma medição
+     * e era lido como o total do projeto.
+     */
+    const merged = mergePages(list);
+    delete out.pages;
+    delete out.pagesTotal;
+    if (merged.pages)
+        out.pages = merged.pages;
+    if (merged.pagesTotal)
+        out.pagesTotal = merged.pagesTotal;
     if (gaps.length > 0)
         out.architectureGaps = gaps;
     if (newComponentHome)

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.351",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {