synthesisui 0.16.482 → 0.16.484

package/dist/baseline-craft.js

@@ -21,6 +21,16 @@ import { body, bodyWrapped, paint } from "./output.js";
  * Vazio e não uma linha vazia: quem chama decide se imprime o título, e um bloco com cabeçalho e
  * nada embaixo é pior que bloco nenhum.
  */
+/** "A and B", "A, B, C, D and 2 more" - quatro nomes cabem numa linha de terminal. */
+function namesOf(names) {
+    const shown = names.slice(0, 4);
+    const rest = names.length - shown.length;
+    if (rest > 0)
+        return `${shown.join(", ")} and ${rest} more`;
+    return shown.length === 1
+        ? shown[0]
+        : `${shown.slice(0, -1).join(", ")} and ${shown[shown.length - 1]}`;
+}
 export function craftLines(craft) {
     if (!craft)
         return [];
@@ -50,7 +60,9 @@ export function craftLines(craft) {
      * a segunda pergunta, e ela merece a segunda linha.
      */
     if (apart)
-        lines.push(...bodyWrapped(`${apart} have no recipe yet: counted apart, never against you.`).map((l) => body(paint.dim(l))));
+        lines.push(...bodyWrapped(craft.unwrittenNames?.length
+            ? `${namesOf(craft.unwrittenNames)} have no recipe yet - nothing in their files paints them - so they are counted apart, never against you.`
+            : `${apart} have no recipe yet: counted apart, never against you.`).map((l) => body(paint.dim(l))));
     /**
      * OS RÓTULOS ALINHADOS PELO MAIS LONGO, e a largura é medida e não estimada: os nomes chegam do
      * servidor, então um padding fixo desalinharia no dia em que uma lente for renomeada lá.

package/dist/claude-md.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { hasHook } from "./agent-wiring.js";
 import { declaredReference } from "./group-role.js";
 import { recallAvailable } from "./memory/availability.js";
+import { readResponsiveForm, responsiveLine } from "./responsive-form.js";
 const START = "<!-- synthesisui:start -->";
 const END = "<!-- synthesisui:end -->";
 /** Reads the installed DSs from the .lock files in _synthesisui/ds/<slug>/. */
@@ -543,9 +544,15 @@ element. Write every user-facing string in that language - labels, empty states,
 \`alt\`. A screen reader pronounces \`aria-label\` using \`lang\`, so a mixed-language interface is
 worse than an untranslated one. If the attribute is wrong, change it rather than writing against
 it.`;
+    /**
+     * E COMO ELE FAZ O RESPONSIVO, medido como o idioma (item 19 da bateria, 29/09): no b9, 100% inline, o agente criou
+     * CSS Modules só para o ponto de quebra, porque ninguém tinha dito como aquele projeto faz.
+     */
+    const form = await readResponsiveForm(projectRoot).catch(() => null);
+    const responsive = form ? `\n\n${responsiveLine(form)}` : "";
     const body = `## Design Systems (via SynthesisUI)
 
-This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}
+This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}${responsive}
 
 ${sections.join("\n")}
 

package/dist/colour-names.js

@@ -204,3 +204,55 @@ export function agentPrompt(plan) {
         "Change a value only where it is used as the line says. Leave every other colour as it is, and do not add or invent a name or a colour - these six were chosen by the person.",
     ].join("\n");
 }
+/**
+ * O UPGRADE TRAZ AS SEIS CORES NOVAS - etapa 01 da jornada "cada um sabe se o seu código está em dia", 29/09.
+ *
+ * Só o `colours` escrevia o bloco, então quem recebia a versão nova de um colega pelo `upgrade` ficava com os valores
+ * velhos no CSS global (medido no teste-e09: `--color-primary: #0070f3` com o sistema em `#2e5078`). Aqui o bloco que
+ * é NOSSO - entre as marcas - tem os valores trocados pelos da versão nova; nada fora dele é tocado.
+ *
+ * O papel de cada linha: pela grafia (`--<prefixo>-<palavra>`) e, quando o nome é o DELE (`--accent`), pela cor de
+ * antes - é a cor que a versão instalada dava àquele papel.
+ */
+export function refreshColourBlock(css, slug, before, after) {
+    const hit = blockMarks.END_RE(slug).exec(css);
+    if (!hit)
+        return { css, changes: [] };
+    const low = (x) => (x ?? "").trim().toLowerCase();
+    const changes = [];
+    const taken = new Set();
+    const block = hit[0].replace(/^(\s*)(--[a-z0-9-]+)(\s*:\s*)([^;]+);/gim, (line, pad, name, colon, value) => {
+        const byWord = SIX_ROLES.find((r) => !taken.has(r) &&
+            new RegExp(`^--[a-z0-9]+-${WORD[r].word}$`, "i").test(name));
+        const role = byWord ??
+            SIX_ROLES.find((r) => !taken.has(r) && before[r] && low(before[r]) === low(value));
+        if (!role)
+            return line;
+        taken.add(role);
+        const to = after[role];
+        if (!to || low(to) === low(value))
+            return line;
+        changes.push({ role, name, from: value.trim(), to });
+        return `${pad}${name}${colon}${to};`;
+    });
+    if (changes.length === 0)
+        return { css, changes };
+    return {
+        css: css.slice(0, hit.index) + block + css.slice(hit.index + hit[0].length),
+        changes,
+    };
+}
+/** O mesmo, no disco: acha o CSS global dele e reescreve só se algum valor mudou. */
+export async function refreshColourBlockOnDisk(root, slug, before, after) {
+    const v = await readVocabulary(root, slug);
+    if (!v.global)
+        return { file: null, changes: [] };
+    const path = join(root, v.global);
+    const css = await readFile(path, "utf8").catch(() => null);
+    if (css == null)
+        return { file: null, changes: [] };
+    const r = refreshColourBlock(css, slug, before, after);
+    if (r.changes.length > 0)
+        await writeFile(path, r.css, "utf8");
+    return { file: v.global, changes: r.changes };
+}

package/dist/commands/add.js

@@ -1,6 +1,5 @@
-import { neverMeasured } from "../never-measured.js";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
@@ -9,18 +8,19 @@ import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.
 import { detectAppDirs } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
+import { nextInstalledAt, readInstalledAt, writeInstalledAt, } from "../installed-at.js";
 import { censusScope } from "../measured-scope.js";
 import { recallAvailable } from "../memory/availability.js";
+import { neverMeasured } from "../never-measured.js";
 import { nextFontFacts } from "../next-font-weights.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { repoStateOf } from "../repo-state.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
-import { detectStack } from "../stack.js";
+import { detectStack, resolveDeps } from "../stack.js";
 import { onlyWhatMatched } from "../their-theme.js";
 import { tongueOf } from "../their-tongue.js";
 import { pointTokensAtTheirNames } from "../their-vars.js";
-import { resolveDeps } from "../stack.js";
 import { tracksAnyOf } from "../tracked.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
@@ -75,6 +75,11 @@ const IGNORED = [
      * turno de quem instalasse faria um arquivo nosso aparecer no `git status` dele.
      */
     ".turn-clock",
+    /**
+     * A HORA EM QUE A VERSÃO ATERROU NESTE CLONE - ver `installed-at.ts` (29/09). Dentro do `.lock` ela fazia dois upgrades
+     * da mesma versão, em branches separadas, darem conflito numa linha só.
+     */
+    ".fetched-at.json",
 ];
 const IGNORE_HEADER = "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +
     "# clone is governed; the measurement and the local record are not, because\n" +
@@ -196,7 +201,10 @@ async function familiesHeNames(root, families) {
     const kept = Object.entries(families).filter(([, v]) => {
         if (typeof v !== "string")
             return true;
-        const first = v.split(",")[0]?.trim().replace(/^["']|["']$/g, "") ?? "";
+        const first = v
+            .split(",")[0]
+            ?.trim()
+            .replace(/^["']|["']$/g, "") ?? "";
         return !first || /^var\(/.test(first) || css.includes(first.toLowerCase());
     });
     return Object.fromEntries(kept);
@@ -392,7 +400,9 @@ export async function add(slug, opts) {
          * E O SISTEMA QUE NUNCA FOI MEDIDO NUM CÓDIGO já nasce assim - ver `neverMeasured` (rodada 5, 27/09):
          * o fork do leigo-5 terminava o `connect` mandando rodar `sync` para uma pasta que não existe.
          */
-        ...(prev?.reading === "none" || neverMeasured(payload.document) ? { reading: "none" } : {}),
+        ...(prev?.reading === "none" || neverMeasured(payload.document)
+            ? { reading: "none" }
+            : {}),
         /** Ver `RegistryPayload.compiler`: é o que faz um conserto de CSS chegar a um install. */
         ...(payload.compiler != null ? { compiler: payload.compiler } : {}),
         ...(payload.rulesStamp ? { rules: payload.rulesStamp } : {}),
@@ -428,17 +438,21 @@ export async function add(slug, opts) {
         /** A memória do que NÓS escrevemos atravessa a re-materialização - ver `RootLock.written`. */
         ...(prev?.written ? { written: prev.written } : {}),
     };
-    const landed = (() => {
-        if (!prev?.fetchedAt)
-            return true;
-        const { fetchedAt: _was, ...before } = prev;
-        return JSON.stringify(before) !== JSON.stringify(identity);
-    })();
-    const lock = {
-        ...identity,
-        fetchedAt: landed || !prev?.fetchedAt ? new Date().toISOString() : prev.fetchedAt,
-    };
+    /**
+     * O `.lock` SEM A HORA - ver `installed-at.ts` (29/09): dois clones na mesma versão escrevem o mesmo arquivo, e a hora
+     * de cada um vai para `.fetched-at.json`, que o git ignora.
+     */
+    const slugDirOfLock = dirname(rootLockPath);
+    const installedAt = nextInstalledAt({
+        prevLock: prev ??
+            null,
+        prevAt: await readInstalledAt(slugDirOfLock, null),
+        identity: identity,
+        now: new Date().toISOString(),
+    });
+    const lock = { ...identity };
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    await writeInstalledAt(slugDirOfLock, installedAt);
     /**
      * O MAPA SOBE AGORA, e é o único momento em que ele é novo.
      *
@@ -637,7 +651,9 @@ export async function add(slug, opts) {
      * `@theme` - vinte linhas depois de "100% of your 59 style decisions carry your own vocabulary".
      */
     const wearsTailwind = await projectWearsTailwind(projectRoot);
-    if (wearsTailwind && !opts.themeFollows && (aligned.dropped.length > 0 || aligned.own.length > 0)) {
+    if (wearsTailwind &&
+        !opts.themeFollows &&
+        (aligned.dropped.length > 0 || aligned.own.length > 0)) {
         console.log(line(
         /**
          * A LINHA DIZ QUE FICARAM DE FORA - e nao AFIRMA por que, porque ela nao sabe.
@@ -779,7 +795,11 @@ export async function add(slug, opts) {
      */
     const stackDeps = await resolveDeps(projectRoot).catch(() => ({}));
     const onNext = projectConfig.target === "next" && "next" in stackDeps;
-    const headHome = onNext ? "app/layout.tsx" : "vite" in stackDeps ? "index.html" : "your root HTML";
+    const headHome = onNext
+        ? "app/layout.tsx"
+        : "vite" in stackDeps
+            ? "index.html"
+            : "your root HTML";
     const fontPlan = onNext
         ? nextFontSnippet({
             families,

package/dist/commands/align.js

@@ -9,6 +9,7 @@ import { unsentEvents } from "../doctor/ledger.js";
 import { readRequests } from "../doctor/requests.js";
 import { declaredReference } from "../group-role.js";
 import { CHECKER_SINCE, installedBehind, MATERIALISER_SINCE, READER_SINCE, } from "../install-marks.js";
+import { readInstalledAt } from "../installed-at.js";
 import { fmt, say } from "../lang.js";
 import { measuredScope } from "../measured-scope.js";
 import { body, bodyWrapped, paint, section, snippet } from "../output.js";
@@ -34,7 +35,8 @@ async function wholeRepoMeasured(root) {
         return false;
     try {
         const c = JSON.parse(raw);
-        const narrowed = (typeof c.scope === "string" && c.scope.trim() !== "") || (Array.isArray(c.scopes) && c.scopes.length > 0);
+        const narrowed = (typeof c.scope === "string" && c.scope.trim() !== "") ||
+            (Array.isArray(c.scopes) && c.scopes.length > 0);
         return c.measured != null && typeof c.measured === "object" && !narrowed;
     }
     catch {
@@ -66,7 +68,10 @@ async function locksIn(root) {
         if (!raw)
             continue;
         try {
-            out.push(JSON.parse(raw));
+            const lock = JSON.parse(raw);
+            /** A hora mora ao lado desde 29/09 - ver `installed-at.ts`; o `.lock` antigo ainda responde. */
+            const at = await readInstalledAt(join(dsDir, entry.name), lock);
+            out.push(at ? { ...lock, fetchedAt: at } : lock);
         }
         catch {
             // lock ilegível - o `status` já reporta isso com o nome do arquivo
@@ -228,7 +233,10 @@ opts = {}) {
      * sistema de 36).
      */
     const scope = await measuredScope(root, lock.slug);
-    if (!scope.system && scope.usage.length === 0 && lock.reading !== "none" && !(await wholeRepoMeasured(root)))
+    if (!scope.system &&
+        scope.usage.length === 0 &&
+        lock.reading !== "none" &&
+        !(await wholeRepoMeasured(root)))
         out.push({
             says: `"${lock.slug}" does not record where it was measured, so a re-measure would read this whole repo instead of the folder the system came from. Sync asks once and remembers the answer.`,
             /**
@@ -521,6 +529,7 @@ export async function versionBehind(root, opts = {}) {
         return repaired;
     if (body.version > lock.version)
         return {
+            kind: "version",
             says: `v${body.version} of "${lock.slug}" is published and this repo is on v${lock.version}. The CSS here and the rules your agent reads are both v${lock.version} - they move together, which is why this is worth saying rather than applying.`,
             run: `npx synthesisui upgrade ${lock.slug}`,
         };
@@ -707,7 +716,7 @@ opts = {}) {
         ...(opts.cli ? { cli: opts.cli } : {}),
         ...(opts.home ? { home: opts.home } : {}),
     }).catch(() => null);
-    if (remote)
+    if (remote && !(opts.skipVersion && remote.kind === "version"))
         items.push(remote);
     return items;
 }

package/dist/commands/colours.js

@@ -98,7 +98,7 @@ export function markedBefore(before, documentJson) {
     return { ...before, ...marked };
 }
 /** As seis cores da versão que está instalada agora - `{}` quando ainda não há nenhuma. */
-async function installedRoles(slugDir) {
+export async function installedRoles(slugDir) {
     const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
     if (typeof lock.version !== "number")
         return {};

package/dist/commands/import.js

@@ -11,7 +11,7 @@ import { PAGES_MAX, pageCompositionOf } from "../census-pages.js";
 import { readCredentials, readProjectConfig, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
 import { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, packagingOf, proposeNewHome, resolvesAs, countsAsOrganization, } from "../doctor/architecture.js";
-import { findBrokenRefs } from "../doctor/broken-refs.js";
+import { findBrokenRefs, findOrphanVars, findSynonyms, synonymLine } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, readRuntime, } from "../doctor/call-sites.js";
 import { asCatalogueTable, describeFallback, fetchCatalogue, } from "../doctor/catalogue-fetch.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
@@ -2620,6 +2620,8 @@ export async function takeCensus(root, opts) {
         }
     }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
+    const orphanVars = findOrphanVars(css, sources);
+    const synonyms = findSynonyms(css, sources);
     const conventions = detectConventions(sources);
     const classStyle = detectClassStyle(sources);
     /**
@@ -2696,6 +2698,8 @@ export async function takeCensus(root, opts) {
             : {}),
         ...(animations.size > 0 ? { animations: [...animations].sort() } : {}),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
+        ...(orphanVars.length > 0 ? { orphanVars } : {}),
+        ...(synonyms.length > 0 ? { synonyms } : {}),
         /**
          * OS SISTEMAS QUE O CSS DELE JÁ CHAMA PELO NOME - ver `wiredSlugs`.
          *
@@ -3051,6 +3055,38 @@ async function summarize(c, root, scope) {
     sayAdoption(c);
     sayCollisions(c);
     await sayBrokenRefs(c, root, scope);
+    sayOrphanVars(c);
+    saySynonyms(c);
+}
+/**
+ * A MESMA COR COM VÁRIOS NOMES - uma linha por cor, até três (item 16 da bateria, 29/09). Propõe o nome que o código
+ * mais lê; quem decide se junta é ele.
+ */
+function saySynonyms(c) {
+    const all = c.synonyms ?? [];
+    if (all.length === 0)
+        return;
+    console.log("");
+    console.log(section("One colour, several names"));
+    for (const g of all.slice(0, 3))
+        console.log(body(synonymLine(g)));
+    if (all.length > 3)
+        console.log(body(paint.faint(`(${all.length - 3} more colours with more than one name)`)));
+}
+/**
+ * DECLARADAS E NUNCA USADAS - uma linha, nunca uma acusação (item 15 da bateria, 29/09).
+ *
+ * No b1 eram três sobras de um tema antigo, e o import passava calado. Quem lê decide se apaga: pode ser de propósito.
+ */
+function sayOrphanVars(c) {
+    const all = c.orphanVars ?? [];
+    if (all.length === 0)
+        return;
+    const names = all.slice(0, 6).map((o) => paint.strong(o.name));
+    const more = all.length > 6 ? ` and ${all.length - 6} more` : "";
+    console.log("");
+    console.log(section("Declared and never used"));
+    console.log(body(`${all.length} variable${all.length === 1 ? "" : "s"} your CSS declares and nothing reads: ${names.join(", ")}${more}. Usually left over from an old theme - yours to delete or keep.`));
 }
 /**
  * OS ESCOPOS QUE VIRARAM UM SISTEMA, e o que cada um perdeu no empate.
@@ -4138,6 +4174,13 @@ const DECIDEM = [
 const NA_TELA_DO_IMPORT = [
     "How this project is organised",
     ...DECIDEM,
+    /**
+     * E AS ÓRFÃS, numa linha (item 15 da bateria, 29/09): no b1 o dev contava três sobras de tema e o import passava
+     * calado. Cabe porque é uma linha só, e ela muda o que ele faz a seguir: apagar ou manter.
+     */
+    "Declared and never used",
+    /** E a mesma cor com vários nomes (item 16 da bateria, 29/09): até três linhas, e cada uma propõe um nome. */
+    "One colour, several names",
 ];
 function sayReach(c) {
     const reach = ladderReach(c.declared);
@@ -4654,6 +4697,20 @@ quiet = false) {
  * token nenhum o sistema inteiro é a semente, e "v1 is your tokens" levava ao contrário. Ver
  * `nao-espelha-o-que-nao-existe.spec.ts`.
  */
+/**
+ * AS CORES QUE O PROJETO NÃO TEM - item 18 da bateria (28/09), liberado por ele em 29/09. No b4 a borda, o sucesso e o
+ * perigo vinham do nosso ponto de partida, e o dev achava que eram dele. O servidor manda quais (`fromSeed`).
+ */
+export function fromSeedLine(roles) {
+    if (roles.length === 0)
+        return null;
+    const list = roles.length === 1
+        ? roles[0]
+        : `${roles.slice(0, -1).join(", ")} or ${roles[roles.length - 1]}`;
+    return roles.length === 1
+        ? `Your code names no ${list} colour, so it comes from our starting point - yours to change on the colours page.`
+        : `Your code names no ${list} colour, so those come from our starting point - yours to change on the colours page.`;
+}
 export function birthLine(name, declared) {
     return declared === 0
         ? `${name} - your code names no token yet, so this system is our starting point, with your colours and sizes measured next to it (listed in the report).`
@@ -5160,6 +5217,15 @@ export async function runImport(opts) {
      */
     if (payload?.primary)
         console.log(body(payload.primary));
+    /**
+     * E AS QUE ELE NÃO TEM (item 18 da bateria, 29/09). Com a porta das cores aberta a frase dela já diz tudo, e com zero
+     * token a frase do nascimento já diz que o sistema inteiro é o ponto de partida - aí esta linha seria repetição.
+     */
+    const seedLine = !payload?.coloursDoor && Object.keys(census.declared ?? {}).length > 0
+        ? fromSeedLine(payload?.fromSeed ?? [])
+        : null;
+    if (seedLine)
+        console.log(body(seedLine));
     /**
      * A PORTA - convite, nunca bloqueio (o ponto 1 que ele aprovou em 28/09). O servidor manda a frase pronta, a mesma
      * que o quadro do sistema mostra, e o link da tela de escolher daquele sistema.

package/dist/commands/sync.js

@@ -13,11 +13,16 @@ import { measuredScope, rememberScope } from "../measured-scope.js";
 import { fromCensus } from "../memory/observation.js";
 import { reportMeasurement } from "../memory/report.js";
 import { mergeCensus } from "../merge-census.js";
-import { describeGrowth, recordGrowthForTurn, whatGrew } from "../what-grew.js";
+import { readVocabulary } from "../new-project-theme.js";
+import { gitFacts, offerNewVersion } from "../new-version.js";
 import { body, paint, section, snippet } from "../output.js";
+import { fetchDesignSystem } from "../registry.js";
 import { repoStateOf } from "../repo-state.js";
+import { describeGrowth, recordGrowthForTurn, whatGrew } from "../what-grew.js";
 import { reportWhatIsLeft } from "./align.js";
+import { installedRoles, roleColours } from "./colours.js";
 import { resolveReadParts, siblingProjects, takeCensus, } from "./import.js";
+import { upgrade } from "./upgrade.js";
 /**
  * What each decision means ON THIS MACHINE - the card decides, the sync
  * enacts. The web never touches the local file; this line is printed right
@@ -321,9 +326,50 @@ export async function sync(opts) {
      * dizendo o que sobrou resolve o que a dúvida realmente era: acabou ou não? Mudo quando não sobrou
      * nada, que é o caso normal.
      */
-    await reportWhatIsLeft(root);
+    /**
+     * UMA VERSÃO NOVA, DITA POR EXTENSO - etapa 02 de "cada um sabe se o seu código está em dia" (29/09): o que mudou,
+     * e o caminho sem conflito. Quando ela foi dita aqui, a lista do fim não a repete.
+     */
+    const offered = await offerNewVersionHere(root, slug, base).catch(() => "current");
+    await reportWhatIsLeft(root, offered === "current" ? {} : { skipVersion: true });
     sayRefused(refused);
 }
+async function offerNewVersionHere(root, slug, base) {
+    const slugDir = join(root, "_synthesisui", "ds", slug);
+    const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
+    if (typeof lock.version !== "number")
+        return "current";
+    const { global } = await readVocabulary(root, slug);
+    return offerNewVersion(root, { slug, version: lock.version }, { globalCss: global }, {
+        latest: async () => {
+            const p = await fetchDesignSystem(base, slug);
+            return {
+                version: p.version,
+                roles: roleColours(p.artifacts["tokens.css"] ?? ""),
+            };
+        },
+        installedRoles: () => installedRoles(slugDir),
+        git: () => gitFacts(root, slug, global),
+        ask: askYesNo,
+        upgrade: (s) => upgrade(s, { registry: base, dir: root }),
+        tty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    });
+}
+async function askYesNo(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await rl.question(question)).trim());
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * O QUE NÃO FOI ENVIADO, DITO POR ÚLTIMO - e o "por último" é o desenho, não um detalhe.
  *
@@ -359,6 +405,16 @@ export async function remeasure(args) {
      * a frase diz que é o esperado, e o `.lock` guarda isso, para o `align` não pedir de novo.
      */
     if (head?.status === 404) {
+        /**
+         * MAS O 404 TAMBÉM É A RESPOSTA A UMA SESSÃO RECUSADA (29/09): a rota não diz "não te conheço" para não revelar
+         * sistema de ninguém. O token de www.synthesisui.com num sync contra o localhost caía aqui, e o `teste-e09-fechamento`,
+         * que TEM leitura, foi marcado como nunca medido. Antes de concluir, pergunta à sessão.
+         */
+        if (!(await sessionAccepted(base, token))) {
+            console.log(section("Sync"));
+            console.log(body(`${base} does not accept this machine's login, so nothing was re-measured - and nothing was marked. Sign in there and run this again: npx synthesisui login --registry ${base}`));
+            return null;
+        }
         await markNoReading(root, slug);
         console.log(section("Sync"));
         console.log(body(`"${slug}" was not read from a repository - it comes from the gallery or was built on the platform - so there is nothing here to re-measure. That is expected, and this repo will stop asking.`));
@@ -376,10 +432,22 @@ export async function remeasure(args) {
      * SEM CENSO GRAVADO NÃO HÁ O QUE REMEDIR CONTRA. Um sistema que nasceu da galeria não tem escopo
      * nem leitura, e medir o repo dele produziria um censo de um projeto que ninguém mapeou para ele.
      */
+    /**
+     * A LEITURA EXISTE, então uma marca "nunca medido" no `.lock` está errada - a que uma sessão recusada deixou antes de
+     * 29/09 (ver o 404 acima). Sai aqui, para o `align` voltar a pedir o que precisa.
+     */
+    if (stored.hasCensus)
+        await unmarkNoReading(root, slug);
+    /**
+     * O SISTEMA DA GALERIA APRENDE COM O QUE ELE CONSTRÓI - item 8 da bateria (28/09), liberado por ele em 29/09.
+     *
+     * Esta resposta era "did not come from an import (...) Import it first", e no b11 tudo o que o agente construiu em cima
+     * do sistema da galeria ficava fora da plataforma. Sem leitura gravada, a medição vai sobre o repositório inteiro (a
+     * mesma queda de escopo que `scopes` abaixo já faz), e a frase diz que é a primeira.
+     */
     if (!stored.hasCensus) {
         console.log(section("Sync"));
-        console.log(body(`"${slug}" did not come from an import, so there is no measurement to refresh. Import it first: npx synthesisui import`));
-        return null;
+        console.log(body(`This is the first measurement of what this project built on "${slug}" - it came from the gallery, so the platform had not read this repo yet. What you created goes to your system's draft; the system's own colours and type stay as they are.`));
     }
     /**
      * A DISTÂNCIA ATÉ O CLI PUBLICADO, dita onde ele já está.
@@ -1048,6 +1116,32 @@ async function askForScope(root) {
 export async function installedSlug(root) {
     return (await installedSlugs(root))[0] ?? null;
 }
+/** A sessão desta máquina vale em `base`? - a mesma pergunta que o `status` faz. Sem resposta, diz que não. */
+async function sessionAccepted(base, token) {
+    const res = await fetch(`${base}/api/auth/get-session`, {
+        headers: { Authorization: `Bearer ${token}` },
+    }).catch(() => null);
+    if (!res?.ok)
+        return false;
+    const who = (await res.json().catch(() => null));
+    return Boolean(who?.user);
+}
+/** Tira do `.lock` a marca de "sem leitura", quando a plataforma diz que a leitura existe. */
+async function unmarkNoReading(root, slug) {
+    const path = join(root, "_synthesisui", "ds", slug, ".lock");
+    const raw = await readFile(path, "utf8").catch(() => "");
+    if (!raw)
+        return;
+    try {
+        const { reading, ...rest } = JSON.parse(raw);
+        if (reading !== "none")
+            return;
+        await writeFile(path, `${JSON.stringify(rest, null, 2)}\n`, "utf8");
+    }
+    catch {
+        /** Um `.lock` ilegível não é deste passo consertar. */
+    }
+}
 /** Anota no `.lock` que a plataforma não tem leitura deste sistema - ver o 404 em `remeasure`. */
 async function markNoReading(root, slug) {
     const path = join(root, "_synthesisui", "ds", slug, ".lock");

package/dist/commands/upgrade.js

@@ -1,14 +1,15 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
-import { speakInHisProject } from "../in-his-form.js";
 import { join } from "node:path";
 import { pinnedHookVersion, wireAgent } from "../agent-wiring.js";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { isOlderCli } from "../cli-version.js";
+import { refreshColourBlockOnDisk } from "../colour-names.js";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
 import { detectAppDirs } from "../global-sheet.js";
+import { speakInHisProject } from "../in-his-form.js";
 import { installedBehind, MATERIALISER_SINCE } from "../install-marks.js";
 import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, theirThemeVars, themeVocabOf, } from "../project-facts.js";
@@ -19,6 +20,7 @@ import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-co
 import { editedSinceWritten, keptLine, readWritten, recordWritten, } from "../written.js";
 import { add } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
+import { installedRoles } from "./colours.js";
 import { doctor } from "./doctor.js";
 /**
  * The highest `v<n>` below `installed` among the folder names given, or the one
@@ -384,6 +386,8 @@ export async function upgrade(asked, opts) {
         console.log(`✓ ${slug} v${installed} is newer than the registry's v${latest.version} - nothing to do.`);
         return;
     }
+    /** As seis cores de ANTES - o bloco do CSS global dele guarda estas (etapa 01, 29/09). */
+    const coloursBefore = await installedRoles(slugDir);
     // 1. re-materialize the artifacts (v<latest>/ + root re-exports + .lock);
     //    setup hints suppressed - an upgrade means the app is already wired.
     await add(slug, {
@@ -392,6 +396,11 @@ export async function upgrade(asked, opts) {
         setupHints: false,
         ...(opts.cli ? { cli: opts.cli } : {}),
     });
+    /**
+     * AS SEIS CORES NOVAS NO CSS GLOBAL DELE - etapa 01 de "cada um sabe se o seu código está em dia", 29/09. Quem
+     * recebia a versão de um colega ficava com os valores velhos no bloco que o `colours` escreveu.
+     */
+    const colourBlock = await refreshColourBlockOnDisk(root, slug, coloursBefore, await installedRoles(slugDir));
     // 2. regenerate YOUR materialized components (the ones `component` wrote)
     const config = await readProjectConfig(root);
     const regenerated = [];
@@ -541,6 +550,12 @@ export async function upgrade(asked, opts) {
     else {
         console.log(body("No breaking changes detected."));
     }
+    if (colourBlock.changes.length > 0) {
+        console.log("");
+        console.log(body(`✓ ${colourBlock.file}: ${colourBlock.changes.length === 1 ? "1 of your six colours" : `${colourBlock.changes.length} of your six colours`} now ${colourBlock.changes.length === 1 ? "has" : "have"} the new value:`));
+        for (const c of colourBlock.changes)
+            console.log(body(`    ${c.name}: ${c.from} → ${c.to}   (${c.role})`));
+    }
     if (regenerated.length > 0) {
         console.log("");
         console.log(body(`Regenerated ${regenerated.length} materialized component(s): ${regenerated.join(", ")}`));
@@ -579,5 +594,5 @@ export async function upgrade(asked, opts) {
  * `button-gen`: "Could not regenerate (...) (removed/renamed in v2?)". Sem cabeçalho, a pasta é a melhor pista.
  */
 export function recipeNameOf(head, entry) {
-    return /Generated by SynthesisUI - "([^"]+)" from the/.exec(head)?.[1] ?? entry;
+    return (/Generated by SynthesisUI - "([^"]+)" from the/.exec(head)?.[1] ?? entry);
 }

package/dist/doctor/broken-refs.js

@@ -174,3 +174,64 @@ export function findBrokenRefs(sources, declared) {
         b.count - a.count ||
         a.name.localeCompare(b.name));
 }
+const THEME_BLOCK = /@theme\b[^{]*\{[^}]*\}/g;
+const DECLARES_VAR = /(--[a-zA-Z0-9_-]+)\s*:/g;
+const READS_IN_JS = /getPropertyValue\(\s*['"`](--[a-zA-Z0-9_-]+)/g;
+const TAILWIND_SHORT = /\((--[a-zA-Z0-9_-]+)\)/g;
+export function findOrphanVars(css, sources) {
+    const declared = new Set();
+    for (const m of css.replace(THEME_BLOCK, "").matchAll(DECLARES_VAR))
+        declared.add(m[1]);
+    if (declared.size === 0)
+        return [];
+    const used = new Set();
+    for (const text of [css, ...sources.map((s) => s.source)]) {
+        for (const m of text.matchAll(VAR_REF))
+            used.add(m[1]);
+        for (const m of text.matchAll(READS_IN_JS))
+            used.add(m[1]);
+        for (const m of text.matchAll(TAILWIND_SHORT))
+            used.add(m[1]);
+    }
+    return [...declared].filter((n) => !used.has(n)).map((name) => ({ name }));
+}
+const DECLARES_COLOUR = /(--[a-zA-Z0-9_-]+)\s*:\s*(#[0-9a-fA-F]{3,8}|rgba?\([^)]*\)|hsla?\([^)]*\))\s*[;}]/g;
+export function findSynonyms(css, sources) {
+    const byValue = new Map();
+    for (const m of css.replace(THEME_BLOCK, "").matchAll(DECLARES_COLOUR)) {
+        const value = m[2].replace(/\s+/g, "").toLowerCase();
+        const names = byValue.get(value) ?? [];
+        if (!names.includes(m[1]))
+            names.push(m[1]);
+        byValue.set(value, names);
+    }
+    const uses = new Map();
+    /** Só nas fontes: a folha `css` é a soma das folhas que também estão lá, e contar as duas dobraria cada leitura. */
+    for (const text of sources.length > 0 ? sources.map((s) => s.source) : [css])
+        for (const m of text.matchAll(VAR_REF))
+            uses.set(m[1], (uses.get(m[1]) ?? 0) + 1);
+    const groups = [];
+    for (const [value, names] of byValue) {
+        if (names.length < 2)
+            continue;
+        groups.push({
+            value,
+            names: names
+                .map((name) => ({ name, uses: uses.get(name) ?? 0 }))
+                .sort((a, b) => b.uses - a.uses),
+        });
+    }
+    return groups.sort((a, b) => b.names.length - a.names.length);
+}
+/** "#2563eb has 4 names: ... Your code reads --brand the most - keeping one would make the rest aliases." */
+export function synonymLine(g) {
+    const listed = g.names
+        .map((n) => `${n.name} (${n.uses > 0 ? `${n.uses}×` : "never read"})`)
+        .join(", ");
+    const top = g.names[0]?.uses ?? 0;
+    const most = g.names.filter((n) => n.uses === top && top > 0).map((n) => n.name);
+    const tail = most.length === 0
+        ? "Nothing reads any of them yet - keeping one would make the rest aliases."
+        : `Your code reads ${most.length === 1 ? most[0] : `${most.slice(0, -1).join(", ")} and ${most[most.length - 1]}`} the most - keeping one would make the rest aliases.`;
+    return `${g.value} has ${g.names.length} names: ${listed}. ${tail}`;
+}

package/dist/install-marks.js

@@ -310,7 +310,11 @@
  * `[color:#ffffff]`, `font-body` em vez de `[font-family:Inter,_sans-serif]`), e a largura em px no degrau vira `w-10`.
  * Um componente escrito antes reprova na própria checagem.
  */
-export const MATERIALISER_SINCE = "0.16.476";
+/**
+ * 0.16.483 (29/09): o `.lock` sai sem a hora (`fetchedAt` vai para `.fetched-at.json`, ignorado pelo git) - dois
+ * upgrades da mesma versão, em branches separadas, davam conflito numa linha só dele. Ver `installed-at.ts`.
+ */
+export const MATERIALISER_SINCE = "0.16.483";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/installed-at.js

@@ -0,0 +1,41 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * A HORA EM QUE A VERSÃO ATERROU NESTE CLONE, FORA DO `.lock` - pedido dele em 29/09 ("tira, neste PR").
+ *
+ * MEDIDO: dois clones trouxeram a mesma versão em branches separadas e o merge parou numa linha só do `.lock` -
+ * `"fetchedAt"`, a hora de cada download. O `globals.css`, os tokens e a pasta da versão juntaram limpo. O `.lock` é
+ * commitado e o resto dele é função da versão, do compilador e das regras; a hora era a única coisa que descrevia UMA
+ * máquina, e é ela que fazia dois upgrades iguais brigarem.
+ *
+ * Então ela mora num arquivo ao lado, na lista do `.gitignore` que o CLI gerencia - como o `.last-sync.json`. Quem lê
+ * (`repairSaid` no align, `installedAt` no repo-state) lê daqui, e do `.lock` antigo quando este arquivo ainda não
+ * existe - um repo instalado antes continua respondendo.
+ */
+export const INSTALLED_AT_FILE = ".fetched-at.json";
+/** A hora nova: anda quando algo aterrou, e fica onde estava quando nada mudou - a mesma regra do `.lock` de antes. */
+export function nextInstalledAt(v) {
+    const was = v.prevAt ?? v.prevLock?.fetchedAt ?? null;
+    if (!v.prevLock || !was)
+        return v.now;
+    const { fetchedAt: _was, ...before } = v.prevLock;
+    const landed = JSON.stringify(before) !== JSON.stringify(v.identity);
+    return landed ? v.now : was;
+}
+export async function readInstalledAt(slugDir, lock) {
+    const raw = await readFile(join(slugDir, INSTALLED_AT_FILE), "utf8").catch(() => null);
+    if (raw) {
+        try {
+            const at = JSON.parse(raw).fetchedAt;
+            if (typeof at === "string")
+                return at;
+        }
+        catch {
+            // ilegível: cai no `.lock` antigo
+        }
+    }
+    return typeof lock?.fetchedAt === "string" ? lock.fetchedAt : null;
+}
+export async function writeInstalledAt(slugDir, at) {
+    await writeFile(join(slugDir, INSTALLED_AT_FILE), `${JSON.stringify({ fetchedAt: at }, null, 2)}\n`, "utf8");
+}

package/dist/merge-census.js

@@ -261,6 +261,13 @@ export function mergeCensus(list) {
          * dele continua lendo o censo como antes.
          */
         scopes: list.map((c, i) => nameOf(c, i)),
+        /**
+         * SEM ÓRFÃS NUM CENSO DE VÁRIOS ESCOPOS: a declarada num escopo pode ser lida no outro, e cada escopo só viu o seu.
+         * Dizer "nunca usada" sem ter olhado tudo seria acusar errado - fica calado (item 15 da bateria, 29/09).
+         */
+        orphanVars: undefined,
+        /** E pelo mesmo motivo os sinônimos: cada escopo contou as leituras só no que viu. */
+        synonyms: undefined,
         declared,
         observed,
         totals,

package/dist/new-version.js

@@ -0,0 +1,201 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { body, section, snippet } from "./output.js";
+export function pathFor(f) {
+    if (f.remoteVersion != null && f.remoteVersion >= f.latest)
+        return "pull";
+    if (f.dirty.length > 0)
+        return "commit-first";
+    return f.tty ? "ask" : "say";
+}
+/** As seis cores que mudaram entre a versão instalada e a publicada, na ordem dos papéis. */
+export function colourChanges(before, after) {
+    const low = (x) => (x ?? "").trim().toLowerCase();
+    return Object.keys(after)
+        .filter((r) => before[r] && after[r] && low(before[r]) !== low(after[r]))
+        .map((role) => ({
+        role,
+        from: before[role],
+        to: after[role],
+    }));
+}
+/**
+ * O QUADRADO DA COR (29/09, pedido dele olhando o terminal: *"deveria ter um quadrado com as cores ao lado do hex"*). Um
+ * bloco com o fundo na cor exata (24 bits); sem terminal, nada - o agente lê texto, e um código de escape é ruído.
+ */
+export function colourSwatch(hex, tty) {
+    const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim());
+    if (!tty || !m)
+        return "";
+    const [r, g, b] = [m[1], m[2], m[3]].map((x) => Number.parseInt(x, 16));
+    return `\u001b[48;2;${r};${g};${b}m  \u001b[0m`;
+}
+/** O aviso, antes de qualquer escrita: as duas versões e o que mudou nas seis cores. */
+export function newVersionLines(v) {
+    const sw = (hex) => {
+        const s = v.swatch?.(hex) ?? "";
+        return s ? `${s} ` : "";
+    };
+    const out = [
+        `v${v.latest} of "${v.slug}" is published and this repo is on v${v.installed}.`,
+    ];
+    if (v.changes.length > 0) {
+        out.push("What changed in your six colours:");
+        for (const c of v.changes)
+            out.push(`    ${c.role.padEnd(11)}${sw(c.from)}${c.from} → ${sw(c.to)}${c.to}`);
+    }
+    else {
+        out.push("None of your six colours changed - the rest (rules, components) is listed in UPGRADE.md once it is here.");
+    }
+    return out;
+}
+function run(cmd, args, cwd, timeout = 8000) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { cwd, timeout, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }, (err, stdout) => resolve(err ? null : stdout.toString()));
+    });
+}
+/**
+ * O `.lock` só difere do commit pelo `reading` que o próprio sync anota (o 404 da leitura, em `markNoReading`)?
+ * Então a mudança é nossa, e o upgrade a reescreve igual - não é trabalho dele a proteger. Achado no PASS de 29/09.
+ */
+async function onlyOurReading(root, lockPath) {
+    const committed = await run("git", ["show", `HEAD:./${lockPath}`], root);
+    const now = await readFile(join(root, lockPath), "utf8").catch(() => null);
+    if (committed == null || now == null)
+        return false;
+    try {
+        const { reading: _a, ...was } = JSON.parse(committed);
+        const { reading: _b, ...is } = JSON.parse(now);
+        return JSON.stringify(was) === JSON.stringify(is);
+    }
+    catch {
+        return false;
+    }
+}
+export async function gitFacts(root, slug, globalCss) {
+    const none = {
+        repo: false,
+        origin: false,
+        dirty: [],
+        remoteVersion: null,
+        remoteRef: null,
+        gh: false,
+    };
+    const inside = await run("git", ["rev-parse", "--is-inside-work-tree"], root);
+    if (inside?.trim() !== "true")
+        return none;
+    const paths = [`_synthesisui/ds/${slug}`, ...(globalCss ? [globalCss] : [])];
+    const status = (await run("git", ["status", "--porcelain", "--", ...paths], root)) ?? "";
+    const lockPath = `_synthesisui/ds/${slug}/.lock`;
+    const dirty = [];
+    for (const f of status
+        .split("\n")
+        .map((l) => l.slice(3).trim())
+        .filter(Boolean)) {
+        if (f === lockPath && (await onlyOurReading(root, lockPath)))
+            continue;
+        dirty.push(f);
+    }
+    let remoteVersion = null;
+    let remoteRef = null;
+    const origin = await run("git", ["remote", "get-url", "origin"], root);
+    if (origin) {
+        /** O fetch só lê; sem rede ele falha calado e o resto segue sem a informação. */
+        await run("git", ["fetch", "--quiet", "origin"], root, 10000);
+        const head = (await run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], root))?.trim();
+        const candidates = [head, "origin/main", "origin/master"].filter(Boolean);
+        const prefix = ((await run("git", ["rev-parse", "--show-prefix"], root)) ?? "").trim();
+        for (const ref of candidates) {
+            const lock = await run("git", ["show", `${ref}:${prefix}_synthesisui/ds/${slug}/.lock`], root);
+            if (lock == null)
+                continue;
+            remoteRef = ref;
+            try {
+                const v = JSON.parse(lock).version;
+                remoteVersion = typeof v === "number" ? v : null;
+            }
+            catch {
+                remoteVersion = null;
+            }
+            break;
+        }
+    }
+    const gh = (await run("gh", ["auth", "status"], root, 5000)) != null;
+    return {
+        repo: true,
+        origin: origin != null,
+        dirty,
+        remoteVersion,
+        remoteRef,
+        gh,
+    };
+}
+/**
+ * O aviso inteiro, com o caminho escolhido. Devolve o que aconteceu - o `sync` usa para não repetir, na lista do que
+ * falta, a linha de versão que acabou de ser dita aqui.
+ */
+export async function offerNewVersion(_root, lock, where, deps, print = (l) => console.log(l)) {
+    const latest = await deps.latest().catch(() => null);
+    if (!latest || latest.version <= lock.version)
+        return "current";
+    const changes = colourChanges(await deps.installedRoles(), latest.roles);
+    const facts = await deps.git();
+    const path = pathFor({
+        tty: deps.tty,
+        dirty: facts.dirty,
+        remoteVersion: facts.remoteVersion,
+        latest: latest.version,
+    });
+    const slug = lock.slug;
+    print("");
+    print(section(`A new version of ${slug}`));
+    for (const l of newVersionLines({
+        slug,
+        installed: lock.version,
+        latest: latest.version,
+        changes,
+        swatch: (hex) => colourSwatch(hex, deps.tty),
+    }))
+        print(body(l));
+    print("");
+    if (path === "pull") {
+        const branch = (facts.remoteRef ?? "origin/main").replace(/^origin\//, "");
+        print(body(`Someone on your team already brought v${latest.version} into ${facts.remoteRef}. Bring it from git instead of upgrading here - doing the same change twice, in two commits, is what makes a conflict:`));
+        print(snippet([`git pull origin ${branch}`]));
+        return path;
+    }
+    if (path === "commit-first") {
+        print(body("You have changes not committed where the upgrade writes. Commit or stash them first, so the upgrade lands in a diff of its own:"));
+        for (const f of facts.dirty)
+            print(body(`    ${f}`));
+        print("");
+        print(body("then:"));
+        print(snippet([`npx synthesisui upgrade ${slug}`]));
+        return path;
+    }
+    if (path === "say") {
+        print(body("To bring it here:"));
+        print(snippet([`npx synthesisui upgrade ${slug}`]));
+        return path;
+    }
+    const yes = await deps.ask(`  Bring v${latest.version} into this repo now? It rewrites _synthesisui/ds/${slug}${where.globalCss ? ` and the six colours in ${where.globalCss}` : ""}. [y/N] `);
+    if (!yes) {
+        print(body("Nothing was changed. When you want it:"));
+        print(snippet([`npx synthesisui upgrade ${slug}`]));
+        return "declined";
+    }
+    await deps.upgrade(slug);
+    print("");
+    print(section("Give it to your team"));
+    print(body("It is in your files now, not in git. Commit it on a branch of its own, so whoever pulls gets it without redoing it:"));
+    print(snippet([
+        `git switch -c synthesisui-${slug}-v${latest.version}`,
+        "git status    # only what the upgrade wrote should be listed",
+        "git add -A",
+        `git commit -m "synthesisui: ${slug} v${latest.version}"`,
+        ...(facts.origin ? ["git push -u origin HEAD"] : []),
+        ...(facts.origin && facts.gh ? ["gh pr create --fill"] : []),
+    ]));
+    return "upgraded";
+}

package/dist/repo-state.js

@@ -26,6 +26,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { readEvents, } from "./doctor/ledger.js";
+import { readInstalledAt } from "./installed-at.js";
 /**
  * O estado de um slug neste projeto, ou nada quando não há `.lock`.
  *
@@ -34,6 +35,8 @@ import { readEvents, } from "./doctor/ledger.js";
  */
 export async function repoStateOf(projectRoot, slug, cli) {
     const lock = await readJson(join(projectRoot, "_synthesisui", "ds", slug, ".lock"));
+    /** A hora mora ao lado do `.lock` desde 29/09 - ver `installed-at.ts`. */
+    const installedAt = await readInstalledAt(join(projectRoot, "_synthesisui", "ds", slug), lock);
     /**
      * O ÚLTIMO DOCTOR, PELO MESMO LEITOR QUE O `sync` USA (`readEvents`). Abrir o arquivo por conta
      * própria aqui seria uma segunda implementação do formato do registro - e a primeira coisa que
@@ -93,9 +96,7 @@ export async function repoStateOf(projectRoot, slug, cli) {
             ? { unrepresentedMatches: doctor.unrepresentedMatches }
             : {}),
         ...(runs.length > 0 ? { runs } : {}),
-        ...(typeof lock?.fetchedAt === "string"
-            ? { installedAt: lock.fetchedAt }
-            : {}),
+        ...(installedAt ? { installedAt } : {}),
     };
     /** Só o `cli` não é estado: sem nada do repo, não há o que reportar. */
     return Object.keys(payload).length > 1 ? payload : null;

package/dist/responsive-form.js

@@ -0,0 +1,85 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const SKIP = new Set([
+    "node_modules",
+    "_synthesisui",
+    ".next",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    ".turbo",
+]);
+/** Um teto, para um monorepo grande não virar uma varredura longa na hora de escrever o bloco. */
+const MAX_FILES = 600;
+const TAILWIND_PREFIX = /\b(?:sm|md|lg|xl|2xl):[a-z-]+/;
+const MEDIA = /@media\b/;
+const MATCH_MEDIA = /\bmatchMedia\s*\(|\buseMediaQuery\s*\(/;
+const INLINE = /\bstyle=\{\{/g;
+const CLASSNAME = /\bclassName=/g;
+async function walk(root) {
+    const out = [];
+    const queue = [root];
+    while (queue.length > 0 && out.length < MAX_FILES) {
+        const dir = queue.shift();
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            if (SKIP.has(e.name))
+                continue;
+            const full = join(dir, e.name);
+            if (e.isDirectory())
+                queue.push(full);
+            else if (/\.(tsx|jsx|ts|js|css|scss|sass|less|html|vue|svelte)$/.test(e.name))
+                out.push(full);
+        }
+    }
+    return out;
+}
+export async function readResponsiveForm(root) {
+    const files = await walk(root);
+    if (files.length === 0)
+        return null;
+    let media = null;
+    let js = null;
+    let inline = 0;
+    let classes = 0;
+    let componentSheets = 0;
+    for (const file of files) {
+        const src = await readFile(file, "utf8").catch(() => "");
+        const rel = relative(root, file);
+        const markup = /\.(tsx|jsx|html|vue|svelte)$/.test(file);
+        const sheet = /\.(css|scss|sass|less)$/.test(file);
+        if (markup && TAILWIND_PREFIX.test(src))
+            return { kind: "tailwind" };
+        if (sheet && !/globals?\.(css|scss)$/.test(file))
+            componentSheets += 1;
+        if (!media && (sheet || markup) && MEDIA.test(src))
+            media = rel;
+        if (!js && /\.(tsx|jsx|ts|js)$/.test(file) && MATCH_MEDIA.test(src))
+            js = rel;
+        if (markup) {
+            inline += src.match(INLINE)?.length ?? 0;
+            classes += src.match(CLASSNAME)?.length ?? 0;
+        }
+    }
+    if (media)
+        return { kind: "media", file: media };
+    if (js)
+        return { kind: "js", file: js };
+    return { kind: "none", inline: inline > classes && componentSheets === 0 };
+}
+/** A frase para o bloco do agente - uma, curta, com o fato medido e o que fazer. */
+export function responsiveLine(form) {
+    switch (form.kind) {
+        case "tailwind":
+            return "**This project makes screens responsive with Tailwind prefixes** (`md:`, `lg:`). Use the same prefixes for a breakpoint - never a new stylesheet or a `matchMedia` hook for it.";
+        case "media":
+            return `**This project makes screens responsive with \`@media\` in its stylesheets** - see \`${form.file}\`. Put a new breakpoint in the stylesheet of the component that needs it, the same way.`;
+        case "js":
+            return `**This project makes screens responsive in code**, with \`matchMedia\` - see \`${form.file}\`. Reuse that for a new breakpoint instead of adding a stylesheet.`;
+        case "none":
+            return form.inline
+                ? "**This project has no breakpoint yet, and it styles inline** (`style={{}}`). If a screen needs one, keep the form: a small `matchMedia` hook next to the component, not a new stylesheet - and say that you added it."
+                : "**This project has no breakpoint yet.** If a screen needs one, add it in the form this project already styles with, and say that you added it.";
+    }
+}

package/package.json

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