synthesisui 0.16.270 → 0.16.271

package/dist/commands/import.js

@@ -17,6 +17,7 @@ import { countShape, describeCoverage, summarizeCoverage, } from "../doctor/cove
 import { classifyAside, crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } from "../doctor/crosswalk.js";
 import { keyframeOffsets, moduleImports, partialCandidates, readGlobalClasses, readModuleCss, readModuleUsage, sheetImports, transcribeModule, } from "../doctor/css-modules.js";
 import { dataContract } from "../doctor/data-contract.js";
+import { inherit, readDeclaredForms, } from "../doctor/declared-forms.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { fragmentsOfSource, fragmentsOfStylesheet, judgeFragments, } from "../doctor/fragments.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
@@ -1659,11 +1660,36 @@ export async function takeCensus(root, opts) {
      * Montado aqui porque é o primeiro momento em que as três coisas existem juntas: os fragmentos
      * vistos, os tokens declarados, e quais arquivos de estilo pertencem a componente admitido.
      */
+    /**
+     * O QUE ELE DECLAROU SOBRE AS FORMAS DELE - lido do disco, offline, antes de julgar.
+     *
+     * `_synthesisui/interpretation.jsonl` é escrito pela ferramenta `declare_interpretation` do MCP e
+     * enviado pelo `sync`. Ler aqui é o que faz a declaração valer na PRÓXIMA medição, sem esperar
+     * deploy nosso - que é a razão de a feature existir.
+     */
+    const declaredForms = await readDeclaredForms(root);
     const ledger = buildLedger(opts?.cli ?? "unknown", judgeFragments([...fragments.flat(), ...styleFiles.flatMap((s) => s.fragments)], declaredValues, admittedStyles, {
         wornGlobal: globalClassesClaimed,
         islandRead: islandClassesRead,
         refused: new Set(skips.map((s) => s.file)),
-    }));
+    }, 
+    /**
+     * AS FORMAS QUE ELE DECLAROU - e é aqui que a declaração dele muda o veredito.
+     *
+     * Sem esta linha o arquivo `interpretation.jsonl` existiria e nada o leria: um `tierColor(gold)`
+     * declarado continuaria contado como `computed`, e o cliente teria ensinado a esteira sem efeito
+     * nenhum. É o defeito do `keep` outra vez, e o guard de órfãos pegou antes de subir.
+     */
+    declaredForms), 
+    /**
+     * OS NOMES QUE ELE DECLARA, para a contagem de `withTheirTokens`.
+     *
+     * Medido no frontend-hub (21/08): um grupo reporta 10.206 declarações "não lidas" e 1.841 delas
+     * (28,8%) usam `var(--...)` de um token dele. O veredito está certo - é o portão recusando página
+     * -, mas o cliente lia "não lida" sobre uma declaração cujo valor está inteiramente no sistema
+     * dele. O contador dá a segunda frase sem apagar a primeira.
+     */
+    new Set(declaredValues.keys()));
     const coverageLines = describeCoverage(coverage, composition, skips.length);
     if (coverageLines.length > 0) {
         say("");
@@ -1965,6 +1991,17 @@ export async function takeCensus(root, opts) {
                 : {}),
         },
         declared: Object.fromEntries(table.byName),
+        /**
+         * AS FORMAS QUE ELE DECLAROU, VIAJANDO COM O CENSO - e sem isto a hierarquia não acumula nada.
+         *
+         * A declaração é escrita na máquina dele (`declare_interpretation` -> `interpretation.jsonl`) e
+         * vale ali no mesmo instante. O que ela NÃO faz sozinha é chegar à plataforma: sem este campo, a
+         * convenção seria dele para sempre, e o degrau `global` - que exige dois USUÁRIOS DISTINTOS -
+         * nunca teria como ser proposto.
+         *
+         * Omitido quando não há nenhuma, que é o caso de todo primeiro import.
+         */
+        ...(declaredForms.length > 0 ? { declaredForms } : {}),
         /**
          * A FOLHA DELE ENTRA POR ÚLTIMO, e a ordem é a resposta a quem manda.
          *
@@ -3670,8 +3707,19 @@ export async function runImport(opts) {
         return;
     }
     const payload = (await res.json().catch(() => null));
+    /**
+     * O QUE ELE HERDA DO TIME, GRAVADO - e é isto que faz a hierarquia render em vez de contabilizar.
+     *
+     * Um segundo repositório do mesmo workspace nasce já sabendo ler a convenção que o primeiro ensinou.
+     * Sem esta linha, cada dev reensinaria a mesma coisa e o degrau `workspace` existiria só como linha
+     * no banco.
+     */
+    const inheritedHere = await inherit(root, payload?.inheritedForms ?? []);
     console.log("");
     console.log(section("Your system exists"));
+    if (inheritedHere > 0) {
+        console.log(body(`${inheritedHere} form${inheritedHere === 1 ? "" : "s"} your team already taught the pipeline apply here too - the next measurement reads them without you declaring anything.`));
+    }
     console.log(body(`${paint.strong(payload?.name ?? "Your system")} - v1 mirrors your tokens exactly, nothing improved yet.`));
     /**
      * ONDE ELE NASCEU, dito pela plataforma e não pelo que foi pedido.

package/dist/commands/mcp.js

@@ -6,6 +6,8 @@ import { pinnedHookVersion } from "../agent-wiring.js";
 import { elementClass, kebabAxis } from "../component-codegen.js";
 import { composePlan, FAMILIES, isFamily, noFamilyAnswer, renderPlan, } from "../compose-context.js";
 import { readToken, resolveRegistry } from "../config.js";
+import { declareForm } from "../doctor/declared-forms.js";
+import { describeTriage, triageLedger } from "../doctor/gap-triage.js";
 import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
@@ -88,6 +90,60 @@ const TOOLS = [
             required: ["value"],
         },
     },
+    {
+        /**
+         * O QUE A ESTEIRA NÃO LEU DESTE REPOSITÓRIO, TRIADO - e a ferramenta que faltava ao agente.
+         *
+         * Medido na auditoria de 21/08: dos 26 comandos, 20 não têm equivalente aqui, e dezenove estão
+         * certos assim - `connect`, `login`, `hook`, `ci` são do dono e da máquina; `add` e `upgrade` são
+         * decisão de versão. Este é o único que faz falta.
+         *
+         * Sem ele, o agente encontra um valor que não virou token e não distingue "lacuna nossa" de "o
+         * portão recusou de propósito" de "convenção dele, que ele pode declarar" - três situações com
+         * ações opostas. O padrão sem resposta é improvisar, que é o evento que a plataforma mais quer
+         * evitar.
+         */
+        /**
+         * DECLARAR COMO LER UMA FORMA DELE - o par do `gaps`, e a razão de ele existir.
+         *
+         * O `gaps` mostra que uma forma não foi lida; esta resolve o caso em que a resposta é DELE. Medido
+         * nas duas populações, `computed` é ~1% do não interpretado - pouco em volume, e o único caso em
+         * que o cliente não precisa esperar o nosso backlog.
+         *
+         * Só o DECLARÁVEL entra: um padrão e um destino. O que exige cálculo (`lighten(color, 20)`) é
+         * leitor, é nosso, e não cabe aqui - ver `declared-forms.ts`.
+         */
+        name: "declare_interpretation",
+        description: 'Teach the pipeline how to read a form of THEIRS that no reader understands - a helper, an accessor, a macro. Give the pattern and the token it means: { kind: "call", match: "tierColor({arg})", resolves: "--color-tier-{arg}" }. It takes effect for THIS project immediately and needs no deploy from us. Only declare what is a straight mapping: if the value is computed (lighten, darken, arithmetic) there is no token to name, and you should say so instead. Call `gaps` first to see which forms are worth declaring.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: ["call", "member", "template", "tagged", "at-rule"],
+                    description: "How they write it: a function call, a property access, a template literal, a tagged template, or an at-rule.",
+                },
+                match: {
+                    type: "string",
+                    description: "The pattern as they write it, with {name} where the value varies: `tierColor({arg})`, `theme.brand`.",
+                },
+                resolves: {
+                    type: "string",
+                    description: "The token it means, reusing the same {name}: `--color-tier-{arg}`. Must name a custom property.",
+                },
+                why: {
+                    type: "string",
+                    description: "One sentence in their terms - somebody reads this before promoting the form to a wider scope.",
+                },
+            },
+            required: ["kind", "match", "resolves"],
+        },
+    },
+    {
+        name: "gaps",
+        description: "What this pipeline did NOT read from this repository, triaged - so you can tell OUR gap from the gate refusing on purpose from a convention of theirs. Leads with the gate, which is most of what a big number is: measured on a real dashboard, 96% of the unread was the gate and not a gap. Reads the census already on disk and measures nothing. Call it before assuming a value is missing, and before filing request_token.",
+        inputSchema: { type: "object", properties: {} },
+    },
     {
         name: "system_doctrine",
         description: "The rules and the philosophy of the installed system - maximum authority, read this BEFORE building anything. It answers from the version this project has pinned, which is the same version whose tokens are on disk, so the rules you follow and the values you write come from one place. It also says when a newer version has been published, without applying it.",
@@ -975,6 +1031,99 @@ query) {
         };
     }
 }
+/**
+ * O QUE A ESTEIRA NÃO LEU, TRIADO - a mesma triagem do comando `gaps`, servida ao agente.
+ *
+ * NÃO MEDE NADA: lê o `census.json` em disco. Medir aqui seria uma segunda leitura dos arquivos dele,
+ * com uma segunda chance de discordar do que a receita diz - a mesma razão pela qual o comando também
+ * não mede.
+ *
+ * E É A MESMA FUNÇÃO, não uma segunda opinião: `triageLedger` e `describeTriage` são as que o terminal
+ * usa. Duas implementações de um julgamento é como elas começam a discordar - e neste repositório isso
+ * já aconteceu com o `customFontFamilies`, que existia em três cópias e quebrou nas três no mesmo dia.
+ */
+/**
+ * REGISTRA A DECLARAÇÃO, e recusa em voz alta o que não é declarável.
+ *
+ * A recusa é o mais importante daqui: um `resolves` que não nomeia token, ou um `{nome}` que o match
+ * não captura, produziriam lixo na receita - e esse tipo de erro só aparece na tela do cliente, semanas
+ * depois. `declareForm` faz os dois portões e a mensagem dele é a que sai aqui.
+ *
+ * OFFLINE: grava em `_synthesisui/interpretation.jsonl` e o `sync` envia. O agente não pode depender de
+ * rede para registrar o que acabou de descobrir.
+ */
+async function declareAnswer(root, args) {
+    try {
+        const form = await declareForm(root, {
+            kind: String(args.kind ?? "call"),
+            match: String(args.match ?? ""),
+            resolves: String(args.resolves ?? ""),
+            ...(args.why ? { why: String(args.why) } : {}),
+        });
+        return fromContract([
+            `Recorded: \`${form.match}\` reads as \`${form.resolves}\`, for this project.`,
+            "",
+            "It applies from the next measurement of this repository, and it needs nothing from us - no deploy, no release. `synthesisui sync` sends it, and from there the platform can see whether other projects write the same way.",
+            "",
+            "Keep building. If you hit a form whose value is COMPUTED rather than named - `lighten(x, 20)`, arithmetic, a conditional - do not declare it: say in your summary that the value is assembled at render time, which is the honest answer.",
+        ].join("\n"));
+    }
+    catch (error) {
+        /** A mensagem de `declareForm` diz exatamente o que está errado no que ele passou. */
+        return {
+            body: `Not recorded. ${error instanceof Error ? error.message : String(error)}`,
+            source: {
+                kind: "none",
+                reason: "token",
+                detail: "declaration refused",
+            },
+        };
+    }
+}
+async function gapsAnswer(root, cli) {
+    const path = join(root, "_synthesisui", "census.json");
+    const raw = await readFile(path, "utf8").catch(() => null);
+    if (!raw) {
+        return {
+            body: `No measurement at \`_synthesisui/census.json\`, so there is nothing to triage yet. A person has to run \`npx synthesisui import --dry\` in the terminal - it is local, needs no account, and it writes that file. Until then, treat a value you cannot resolve as unknown rather than as a gap.`,
+            source: { kind: "none", reason: "system", detail: "no census on disk" },
+        };
+    }
+    let ledger;
+    try {
+        ledger = JSON.parse(raw).ledger;
+    }
+    catch {
+        return {
+            body: `\`_synthesisui/census.json\` is not readable JSON, so the triage cannot run. Say so rather than guessing what is missing.`,
+            source: { kind: "none", reason: "system", detail: "census not JSON" },
+        };
+    }
+    if (!ledger) {
+        return {
+            body: `The census on disk carries no style ledger - it was measured by a CLI older than the one that records what went unread. A person can re-measure with \`npx synthesisui import --dry\`.`,
+            source: {
+                kind: "none",
+                reason: "system",
+                detail: "census has no ledger",
+            },
+        };
+    }
+    const lines = describeTriage(triageLedger(ledger, cli));
+    return fromContract([
+        ...lines,
+        "",
+        /**
+         * O QUE FAZER COM CADA VEREDITO - porque uma triagem sem ação vira um relatório que o agente lê
+         * e ignora. E a ordem é a das consequências: o portão primeiro, porque é a maior parte.
+         */
+        "What to do with each of these:",
+        "  NOT A READING GAP - nothing to do, and nothing to file. Those styles belong to components this scope does not admit; the ones wearing a token of theirs already have their value in the system.",
+        "  NO READER FOR THIS SHAPE - ours to build. File request_token for the value you needed so it becomes a decision somebody can make, then keep going.",
+        "  THE SHAPE IS READ, THE VALUE IS NOT - the value sits outside their scales. That is a naming decision, and the screen offers it: do not invent a name here.",
+        "  A value assembled at render time cannot be read from source at all. Use what the recipe declares, and say in your summary that the computed value was left as it is.",
+    ].join("\n"));
+}
 async function describeComponent(root, name) {
     const { documents, requires, table } = await loadSystem(root);
     let recipe;
@@ -1293,7 +1442,7 @@ const SUBJECT_ARG = {
 async function callTool(root, name, args, 
 /** A versão que reporta o estado do repo no ping - ver `repoStateOf`. */
 cli) {
-    const answer = await runTool(root, name, args);
+    const answer = await runTool(root, name, args, cli);
     const gesture = BY_COMPONENT[name];
     const subject = SUBJECT_ARG[name];
     const target = subject
@@ -1347,12 +1496,24 @@ async function localObservation(root) {
         return null;
     }
 }
-async function runTool(root, name, args) {
+async function runTool(root, name, args, 
+/**
+ * A VERSÃO QUE ESTÁ TRIANDO - e só o `gaps` precisa dela.
+ *
+ * A triagem compara o CLI que MEDIU o censo com o que está triando: sem isso, o veredito
+ * `older-cli` não existe, e alguém escreve um leitor para uma forma que a versão seguinte já lê.
+ * Opcional porque os specs chamam sem ela, e ali a versão não é o que está sob teste.
+ */
+cli) {
     switch (name) {
         case "check_file":
             return checkFile(root, String(args.path ?? "."));
         case "find_token":
             return findToken(root, String(args.value ?? ""));
+        case "declare_interpretation":
+            return declareAnswer(root, args);
+        case "gaps":
+            return gapsAnswer(root, cli ?? "unknown");
         case "system_doctrine":
             return fromContract(await systemDoctrine(root));
         case "list_components":

package/dist/commands/sync.js

@@ -2,6 +2,7 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { isOlderCli } from "../cli-version.js";
 import { readToken, resolveRegistry } from "../config.js";
+import { inherit, readDeclaredForms, } from "../doctor/declared-forms.js";
 import { markSent, readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { describeDelta, fingerprintReadings, readSyncMark, writeSyncMark, } from "../last-sync.js";
@@ -127,6 +128,8 @@ export async function sync(opts) {
     const events = await readEvents(root);
     const repo = opts.cli ? await repoStateOf(root, slug, opts.cli) : null;
     const requests = await readRequests(root);
+    /** O que ele declarou sobre as formas dele - ver `declared-forms.ts`. */
+    const forms = await readDeclaredForms(root);
     if (events.length === 0 && requests.length === 0) {
         console.log(section("Sync"));
         console.log(body("Nothing recorded yet. The record fills as the hook checks writes and doctor runs."));
@@ -147,6 +150,16 @@ export async function sync(opts) {
             slug,
             events,
             requests,
+            /**
+             * AS FORMAS QUE ELE DECLAROU, e sem isto elas nunca saíam da máquina dele.
+             *
+             * O import leva as que existiam NAQUELE momento - e declarar depois é o caso NORMAL, porque ele
+             * só descobre a lacuna usando o sistema. Sem esta linha, uma convenção declarada na terça
+             * ficaria dele para sempre, e a plataforma nunca saberia que outro cliente escreve igual.
+             *
+             * Omitido quando não há nenhuma, como todo campo aditivo deste payload.
+             */
+            ...(forms.length > 0 ? { declaredForms: forms } : {}),
             ...(repo ? { repo } : {}),
         }),
     }).catch(() => null);
@@ -167,8 +180,20 @@ export async function sync(opts) {
      */
     await markSent(root, events);
     const out = (await res.json());
+    /**
+     * O QUE ELE HERDA DO TIME, GRAVADO - e é isto que faz a hierarquia render em vez de contabilizar.
+     *
+     * A plataforma devolve as formas de escopo `workspace`, `user` ou `global` que alcançam este
+     * contexto. Sem gravá-las aqui, o colega dele reensinaria a mesma convenção e o degrau existiria só
+     * como linha no banco. O que ele já declarou neste projeto vence - a mais estreita ganha.
+     */
+    const gained = await inherit(root, out.inheritedForms ?? []);
     console.log(section("Sync"));
     console.log(body(`${out.eventsReceived} checks sent, ${out.eventsNew} new. ${out.requestsNow} open request${out.requestsNow === 1 ? "" : "s"}.`));
+    if (gained > 0) {
+        console.log("");
+        console.log(body(`${gained} form${gained === 1 ? "" : "s"} your team already taught the pipeline now apply here too - the next measurement reads them without you declaring anything.`));
+    }
     // Closed by CHECKING, not by word: the installed css now delivers these.
     if (verified.length > 0) {
         console.log("");

package/dist/doctor/declared-forms.js

@@ -0,0 +1,166 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * COMO LER UMA FORMA QUE A ESTEIRA NÃO ENTENDE, DECLARADO PELO CLIENTE - e valendo no mesmo instante.
+ *
+ * O PROBLEMA. Quando nenhum leitor entende uma forma, existe uma saída só: nós escrevermos o leitor, e
+ * o cliente esperar o nosso backlog. Medido nas duas populações, o `computed` - valor montado em tempo
+ * de render - é ~1% do não interpretado: 117 de 10.843 no frontend-hub, 2 de 222 no codelevel. Pouco em
+ * volume, e o único caso em que o cliente pode resolver HOJE.
+ *
+ * A DISTINÇÃO QUE DECIDE TUDO:
+ *
+ *     DECLARÁVEL      um padrão e um destino. É DADO, e não exige código nosso
+ *                     tierColor(x)  ->  --color-tier-{x}
+ *                     theme.brand   ->  --color-brand-blue
+ *     NÃO DECLARÁVEL  exige cálculo, e aí é leitor - nosso, e só existe em `global`
+ *                     lighten(color, 20)   o resultado não é um nome
+ *
+ * OFFLINE-FIRST, como o resto do CLI: grava em `_synthesisui/interpretation.jsonl` e o `sync` envia.
+ * Mesmo desenho de `requests.jsonl`, e pelo mesmo motivo - o agente não pode depender de rede para
+ * registrar o que acabou de descobrir.
+ *
+ * E ISTO NÃO É REGRA DE CONDUTA: muda o que NÓS conseguimos ler, não o que ele pode escrever. O
+ * `--color-tier-gold` dele continua intacto no CSS. Por isso a declaração é promovível entre escopos -
+ * é conhecimento de interpretação, não lei sobre o código de ninguém.
+ */
+export const FORMS_FILE = "interpretation.jsonl";
+/** Os `{nome}` de um padrão, na ordem em que aparecem. */
+const holes = (s) => [...s.matchAll(/\{([a-z0-9_]+)\}/gi)].map((m) => m[1]);
+/**
+ * A CHAVE, derivada do match - e é o que faz dois clientes com o mesmo helper contarem como um.
+ *
+ * Só o nome, sem argumento: `tierColor({arg})` e `tierColor({tier})` são o mesmo helper escrito por
+ * duas pessoas, e tratá-los como formas diferentes mataria a contagem de origem independente.
+ */
+export function formKey(kind, match) {
+    const name = match.split("(")[0].trim();
+    return `${kind}:${name}`;
+}
+/**
+ * APLICA AS FORMAS DECLARADAS a um valor que nenhum leitor resolveu.
+ *
+ * Devolve `null` quando nada casa, e é o que permite o chamador seguir tratando aquilo como não lido em
+ * vez de inventar um token.
+ *
+ * O ARGUMENTO TEM QUE SER PALAVRA SIMPLES: `tierColor(user.tier)` é montado em runtime de verdade - o
+ * argumento é uma expressão, e transformá-lo em `--color-tier-user.tier` produziria um token que não
+ * existe. Aquilo continua sendo `computed`, e dizer isso é mais honesto que resolver errado.
+ */
+export function applyDeclaredForms(value, forms) {
+    const text = value.trim();
+    for (const form of forms) {
+        const name = form.match.split("(")[0].trim();
+        const hole = holes(form.match)[0];
+        if (!hole) {
+            /** Sem lacuna: o match é literal, e o valor tem que ser exatamente ele. */
+            if (text === name)
+                return `var(${form.resolves})`;
+            continue;
+        }
+        /** `nome( "arg" )` - espaço e aspas porque código real tem os dois. */
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const call = new RegExp(`^${escaped}\\s*\\(\\s*["']?([a-z0-9_-]+)["']?\\s*\\)$`, "i").exec(text);
+        if (!call)
+            continue;
+        return `var(${form.resolves.replaceAll(`{${hole}}`, call[1])})`;
+    }
+    return null;
+}
+/**
+ * ================================================================================================
+ * DAQUI PARA BAIXO É O QUE TOCA DISCO, e é o que NÃO tem gêmeo do outro lado.
+ *
+ * O bloco acima - o tipo, `holes`, `formKey` e `applyDeclaredForms` - é byte-idêntico a
+ * `apps/web/src/lib/ds/declared-forms-shape.ts`, garantido por spec. Ele está contíguo de propósito:
+ * um bloco puro espalhado entre funções de arquivo é um bloco que ninguém consegue comparar, e a
+ * comparação é a única defesa contra as duas cópias divergirem.
+ * ================================================================================================
+ */
+const path = (root) => join(root, "_synthesisui", FORMS_FILE);
+/**
+ * DECLARA, com dois portões que existem porque o erro deles só aparece na tela do cliente.
+ *
+ *   o destino tem que NOMEAR UM TOKEN     senão a esteira escreve lixo na receita
+ *   todo `{nome}` do destino tem que      `--color-tier-{tier}` com um match que captura `{arg}`
+ *   ser capturado pelo match              produziria a string literal `{tier}` no nome do token
+ */
+export async function declareForm(root, form) {
+    const resolves = form.resolves.trim();
+    if (!resolves.startsWith("--")) {
+        throw new Error(`"${resolves}" does not name a token. A declared form has to resolve to a custom property (\`--something\`) - anything else would put a literal in the recipe.`);
+    }
+    const captured = new Set(holes(form.match));
+    const missing = holes(resolves).filter((h) => !captured.has(h));
+    if (missing.length > 0) {
+        throw new Error(`"${resolves}" uses {${missing.join("}, {")}}, which the match "${form.match}" never captures. The token name would come out with the braces still in it.`);
+    }
+    const full = {
+        key: formKey(form.kind, form.match),
+        kind: form.kind,
+        match: form.match.trim(),
+        resolves,
+        ...(form.why ? { why: form.why } : {}),
+        at: form.at ?? new Date().toISOString(),
+    };
+    await mkdir(dirname(path(root)), { recursive: true });
+    await appendFile(path(root), `${JSON.stringify(full)}\n`, "utf8");
+    return full;
+}
+/**
+ * O QUE ELE DECLAROU, com a ÚLTIMA palavra por forma.
+ *
+ * Append-only no disco e dedup na leitura, como o ledger: uma correção não precisa reescrever o
+ * arquivo, e o histórico de que ele mudou de ideia continua lá para quem for promover.
+ */
+export async function readDeclaredForms(root) {
+    const raw = await readFile(path(root), "utf8").catch(() => "");
+    if (!raw)
+        return [];
+    const byKey = new Map();
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const form = JSON.parse(line);
+            if (form.key)
+                byKey.set(form.key, form);
+        }
+        catch {
+            /** Uma linha corrompida não pode custar as outras - o mesmo contrato do ledger. */
+        }
+    }
+    return [...byKey.values()];
+}
+/**
+ * O QUE ELE HERDA DO TIME, GRAVADO AQUI - e sem isto a hierarquia é contabilidade sem efeito.
+ *
+ * A plataforma devolve, no import e no `sync`, as formas de escopo mais largo que alcançam este
+ * contexto: a convenção do workspace, a do usuário, a global. Sem gravá-las, o colega dele reensinaria
+ * a mesma coisa - e o degrau `workspace` existiria só como linha no banco.
+ *
+ * MARCADAS COMO HERDADAS: elas entram no mesmo arquivo, com `from` dizendo de onde vieram. Isso é o que
+ * permite a próxima medição usá-las e ninguém confundi-las com o que ele mesmo escreveu - e é o que
+ * evita reenviar de volta o que a plataforma acabou de mandar.
+ */
+export async function inherit(root, forms) {
+    const mine = new Set((await readDeclaredForms(root)).map((f) => f.key));
+    let wrote = 0;
+    for (const form of forms) {
+        /** O que ele já declarou aqui vence: a mais estreita ganha, como em toda a hierarquia. */
+        if (mine.has(form.key) || !form.resolves)
+            continue;
+        await mkdir(dirname(path(root)), { recursive: true });
+        await appendFile(path(root), `${JSON.stringify({
+            key: form.key,
+            kind: form.kind,
+            /** O nome sai da chave: `call:tierColor` -> `tierColor({arg})`. */
+            match: `${form.key.split(":")[1] ?? form.key}({arg})`,
+            resolves: form.resolves,
+            from: form.scope,
+            at: new Date().toISOString(),
+        })}\n`, "utf8");
+        wrote += 1;
+    }
+    return wrote;
+}

package/dist/doctor/fragments.js

@@ -13,6 +13,7 @@
  * se ele foi lido é a interpretação, que roda depois. Juntar as duas coisas numa função seria
  * repetir a mistura que a tabela de cobertura já paga: forma e veredito são fatos diferentes.
  */
+import { applyDeclaredForms } from "./declared-forms.js";
 import { readStyledComponents, readSxProps } from "./style-props.js";
 import { readInlineStyle, transcribe } from "./transcribe.js";
 /** `className="…"` e `className={"…"}` - o literal puro. */
@@ -279,6 +280,18 @@ const STRUCTURE = new Set([
     "inline",
     "contents",
 ]);
+/**
+ * UMA FORMA DECLARADA POR ELE RESOLVE ISTO? - o portão que transforma `computed` em lido.
+ *
+ * Aqui e não dentro de `applyDeclaredForms` porque o julgamento só precisa do SIM ou NÃO: o valor
+ * resolvido é assunto do transcritor, e duplicar a resolução em dois lugares é como eles começam a
+ * discordar.
+ */
+function declaredReads(text, forms) {
+    if (forms.length === 0)
+        return false;
+    return applyDeclaredForms(text, forms) != null;
+}
 export function judgeFragments(seen, declared, admitted, 
 /**
  * AS CLASSES DE FOLHA GLOBAL QUE UM COMPONENTE ADMITIDO VESTIU - ver
@@ -297,7 +310,18 @@ export function judgeFragments(seen, declared, admitted,
  *   refused      arquivos de componente que o portão recusou de propósito: a classe
  *                deles é `component-not-admitted` (by-design), nunca lacuna de valor
  */
-elsewhere) {
+elsewhere, 
+/**
+ * AS FORMAS QUE ELE DECLAROU - e é o que faz um `computed` deixar de ser lacuna.
+ *
+ * Medido nas duas populações, `computed` é ~1% do não interpretado: 117 de 10.843 no frontend-hub, 2
+ * de 222 no codelevel. Pouco em volume, e o único caso em que o CLIENTE resolve hoje, sem deploy
+ * nosso - ver `declared-forms.ts`.
+ *
+ * Último parâmetro e opcional: quem julga de um contexto sem projeto (um spec, o hook) não tem
+ * declaração nenhuma, e ali o veredito é o de sempre.
+ */
+forms = []) {
     const wornGlobal = elsewhere?.wornGlobal ?? new Set();
     const islandRead = elsewhere?.islandRead ?? new Map();
     const refused = elsewhere?.refused ?? new Set();
@@ -359,7 +383,9 @@ elsewhere) {
                 if (f.shape === "template" && !/[a-z]/i.test(literal))
                     return modules.length > 0
                         ? { ...f, read: true }
-                        : { ...f, read: false, reason: "computed" };
+                        : declaredReads(f.text, forms)
+                            ? { ...f, read: true }
+                            : { ...f, read: false, reason: "computed" };
                 const t = transcribe(literal.split(/\s+/).filter(Boolean), declared);
                 /**
                  * AS QUATRO CASAS DA TRANSCRIÇÃO, não três. O `dark:data-[checked]:bg-…` do
@@ -407,7 +433,9 @@ elsewhere) {
                 const read = Object.keys(readInlineStyle(`style={{${f.text}}}`)).length > 0;
                 return read
                     ? { ...f, read: true }
-                    : { ...f, read: false, reason: "computed" };
+                    : declaredReads(f.text, forms)
+                        ? { ...f, read: true }
+                        : { ...f, read: false, reason: "computed" };
             }
             case "css":
                 return admitted.has(f.file)

package/dist/doctor/gap-triage.js

@@ -132,6 +132,10 @@ export function triageLedger(ledger, triagedBy) {
             work,
             because: group.because,
             examples: group.examples,
+            /** Passa adiante, e ausente quando é zero - a mesma regra do ledger. */
+            ...(group.withTheirTokens && group.withTheirTokens > 0
+                ? { withTheirTokens: group.withTheirTokens }
+                : {}),
         };
     });
     gaps.sort((a, b) => rank[a.verdict] - rank[b.verdict] || b.uses - a.uses);
@@ -187,7 +191,17 @@ export function describeTriage(t) {
         if (group.length === 0)
             continue;
         const total = t.totals[verdict];
-        lines.push("", `${label[verdict]} - ${total} fragment${total === 1 ? "" : "s"}, ${unread > 0 ? Math.round((total / unread) * 100) : 0}% of what was not interpreted`);
+        /**
+         * QUANTOS DESTE VEREDITO JÁ VESTEM UM TOKEN DELE - a segunda frase de um número grande.
+         *
+         * Medido no frontend-hub: o `by-design` soma 10.394 fragmentos, e 1.841 deles carregam `var(--)`
+         * de um token declarado. "Nenhum trabalho aqui" já era verdade; o que faltava era dizer que o
+         * VALOR daquilo está no sistema, e não só que não há o que consertar.
+         */
+        const theirs = group.reduce((n, g) => n + (g.withTheirTokens ?? 0), 0);
+        lines.push("", `${label[verdict]} - ${total} fragment${total === 1 ? "" : "s"}, ${unread > 0 ? Math.round((total / unread) * 100) : 0}% of what was not interpreted${theirs > 0
+            ? ` — and ${theirs} of them already wear a token you declare, so their value is in the system`
+            : ""}`);
         for (const gap of group) {
             lines.push(`  ${gap.uses} ${gap.shape} in ${gap.files} file${gap.files === 1 ? "" : "s"} (${gap.share}%) - ${gap.work}`);
             for (const example of gap.examples.slice(0, 2))

package/dist/doctor/style-ledger.js

@@ -101,7 +101,15 @@ const BECAUSE = {
  * texto de um fragmento LIDO é descartado aqui de propósito - a interpretação dele já vive no
  * look, e reter as duas cópias é o que dobraria o censo.
  */
-export function buildLedger(cli, seen) {
+export function buildLedger(cli, seen, 
+/**
+ * OS NOMES QUE ELE DECLARA - para a contagem de `withTheirTokens`.
+ *
+ * Opcional porque quem chama de um contexto sem censo (o hook, um spec) não tem a tabela dele à
+ * mão, e ali a conta simplesmente não é feita. Um número ausente é honesto; um zero inventado diria
+ * que nenhuma declaração usa token.
+ */
+declared) {
     const counted = blank();
     const interpreted = blank();
     const groups = new Map();
@@ -122,9 +130,24 @@ export function buildLedger(cli, seen) {
             examples: [],
             unreadable: [],
             seenFiles: new Set(),
+            withTheirTokens: 0,
         };
         group.uses += 1;
         group.seenFiles.add(f.file);
+        /**
+         * O VALOR É UM TOKEN DELE? A referência tem que apontar para algo DECLARADO - um
+         * `var(--nao-existe)` é descartado pelo browser, e ali não há token a reivindicar. Mesma regra do
+         * desvio de `binding-not-read` em `fragments.ts`, e de propósito: duas contagens da mesma pergunta
+         * é como elas começam a discordar.
+         */
+        if (declared) {
+            for (const m of f.text.matchAll(/var\(\s*(--[a-z0-9-]+)/gi)) {
+                if (declared.has(m[1])) {
+                    group.withTheirTokens = (group.withTheirTokens ?? 0) + 1;
+                    break;
+                }
+            }
+        }
         if (group.examples.length < 3 &&
             !group.examples.some((e) => e.file === f.file))
             group.examples.push({
@@ -162,7 +185,12 @@ export function buildLedger(cli, seen) {
         counted,
         interpreted,
         unread: [...groups.values()]
-            .map(({ seenFiles, ...group }) => ({ ...group, files: seenFiles.size }))
+            .map(({ seenFiles, withTheirTokens, ...group }) => ({
+            ...group,
+            files: seenFiles.size,
+            /** Ausente quando é zero: um campo zerado em todo grupo é ruído em cada relatório. */
+            ...(withTheirTokens && withTheirTokens > 0 ? { withTheirTokens } : {}),
+        }))
             .sort((a, b) => b.uses - a.uses),
     };
 }
@@ -198,7 +226,17 @@ export function describeLedger(l) {
         lines.push(`  ${SHAPE_LABEL[shape].padEnd(28)} ${String(seen).padStart(6)} seen  ${String(got).padStart(6)} interpreted${got === seen ? "" : `  (${seen - got} listed below)`}`);
     }
     for (const g of l.unread) {
-        lines.push(`  ${g.uses} ${g.shape}${g.uses === 1 ? "" : "s"} in ${g.files} file${g.files === 1 ? "" : "s"} - ${g.because}`);
+        /**
+         * A SEGUNDA FRASE, quando parte daquilo já veste um token dele - ver `withTheirTokens`.
+         *
+         * Sem ela o cliente lê "10.206 não lidas" e conclui que a plataforma não entendeu o repositório
+         * dele. No frontend-hub, 1.841 daquelas (28,8%) carregam `var(--)` de um token que ele declara: o
+         * valor está inteiramente no sistema, e o que falta é só saber qual elemento o veste.
+         */
+        const theirs = g.withTheirTokens && g.withTheirTokens > 0
+            ? ` — and ${g.withTheirTokens} of them already wear a token you declare, so their value is in the system`
+            : "";
+        lines.push(`  ${g.uses} ${g.shape}${g.uses === 1 ? "" : "s"} in ${g.files} file${g.files === 1 ? "" : "s"} - ${g.because}${theirs}`);
         for (const e of g.examples)
             lines.push(`      ${e.file}:${e.line}  ${e.text.slice(0, 80)}`);
     }

package/dist/install-marks.js

@@ -244,7 +244,16 @@ export const CHECKER_SINCE = "0.16.250";
  */
 /** 0.16.269 -> 0.16.270 pelo mesmo motivo do MATERIALISER acima: o 0.16.269 foi publicado sem o
  *  leitor de keyframes globais, e uma marca que aponta para ele cala o aviso para quem o instalou. */
-export const READER_SINCE = "0.16.270";
+/**
+ * 0.16.270 -> 0.16.271: o ledger passou a contar quantos fragmentos NÃO LIDOS já vestem um token que
+ * ele declara (`withTheirTokens`). É campo novo no censo, então um censo medido antes não o tem - e a
+ * segunda frase do relatório ("1.841 delas já usam os seus tokens") não pode ser dita sobre ele.
+ *
+ * A marca aponta para a versão DESTE PR, nunca para a que o `package.json` já carregava: o 0.16.270 foi
+ * publicado antes deste código existir, e uma marca nele calaria o aviso para quem o instalou. Mesma
+ * lição de algumas horas antes, na mesma sessão.
+ */
+export const READER_SINCE = "0.16.271";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/package.json

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