synthesisui 0.16.421 → 0.16.423

package/dist/guide.js

@@ -293,8 +293,49 @@ toolsReachable = false,
  * essa porta; deixá-la entreaberta um nível acima seria vigiá-la em vez de fechá-la
  * (CLAUDE.md, Parte I, seção 6).
  */
-fontFacts) {
+fontFacts, 
+/**
+ * O VOCABULÁRIO DESTE REPOSITÓRIO - `tongueFromArtifacts`, ou `null` quando não há folha para ler.
+ *
+ * O QUE ISTO CONSERTA, e é a razão de existir desta etapa: este arquivo é o que o agente DELE lê
+ * antes de escrever, e ele ensinava a nossa grafia. *"Color: `var(--ds-color-semantic-<role>)`"*
+ * é uma instrução para escrever a NOSSA variável no código dele - e ela só resolve com a nossa
+ * folha carregada, que é o que `INV-GERAL-13` proíbe. Um guia que ensina isso produz a violação
+ * sem que ninguém decida nada: o agente obedece.
+ *
+ * Com o vocabulário em mão, cada linha abaixo diz o nome que o código DELE dá àquele valor - ou o
+ * valor, quando o código dele não nomeia nenhum.
+ *
+ * OBRIGATÓRIO, pelo mesmo argumento de `fontFacts` logo acima: um argumento opcional aqui é um
+ * argumento que um chamador novo esquece, e o esquecimento devolve a nossa grafia ao arquivo que
+ * mais a propaga.
+ */
+tongue) {
     const { document: doc, slug, name, version } = payload;
+    /**
+     * COMO ISTO SE ESCREVE NO CÓDIGO DELE - a mesma resposta que a materialização usa.
+     *
+     * `var(--nome-dele)` quando o repositório dele nomeia aquele valor; o valor literal quando não.
+     * Sem vocabulário (projeto que nunca buildou, folha ausente) a resposta é `null`, e quem chama
+     * DIZ isso em vez de imprimir uma grafia que ninguém pode escrever.
+     */
+    const saysAs = (ours) => {
+        if (!tongue)
+            return null;
+        const theirs = tongue.names.get(ours);
+        if (theirs)
+            return `var(${theirs})`;
+        return tongue.values.get(ours) ?? null;
+    };
+    /** `spacing` -> `md → var(--gap-md)`, para cada degrau que o vocabulário alcança. */
+    const family = (prefix, keys) => {
+        const said = keys
+            .map((k) => ({ k, as: saysAs(`--ds-${prefix}-${kebab(k)}`) }))
+            .filter((x) => x.as !== null);
+        return said.length > 0
+            ? said.map((x) => `\`${x.k}\` → \`${x.as}\``).join(", ")
+            : list(keys);
+    };
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
     /**
@@ -339,8 +380,6 @@ fontFacts) {
      */
     const fontPlan = nextFontSnippet({
         families: foundations.typography.families,
-        slug,
-        seam: payload.fontSeam,
         facts: fontFacts,
         /** Os pesos que ELE declara - ver `declaredWeights`. O guia é o arquivo que o agente dele cola. */
         declaredWeights: foundations.typography.weights,
@@ -548,7 +587,10 @@ It writes a **deterministic scaffold**: the page uses this DS's \`.ds-*\` recipe
 path-classes, paired with a co-located scoped CSS (Next target) that carries the **responsive** media
 queries and the **CSS-only hamburger** - so the page is mobile-ready out of the box. **Refine it in
 place** - wire real data, split into components, swap the chart/icon/media placeholders - but keep the
-\`data-ds="${slug}"\` wrapper and the \`.ds-*\` / layout classes so it stays on-system. Run
+wrapper and the \`.ds-*\` / layout classes: the stylesheet next to the page carries the rules for the
+ones it wears, scoped to that wrapper - the command says how many came along, so the page stands on
+its own with nothing imported. A \`.ds-*\` you ADD while refining has no rule there; bring that piece
+in with \`synthesisui component\` instead. Run
 \`synthesisui init\` once to set the target (next/general) and the output folder.
 
 ## Single components as YOUR code
@@ -560,8 +602,8 @@ synthesisui component ${slug} button
 It writes \`<componentsDir>/button/\` with \`button.tsx\` (+ colocated \`button.css\` in the default
 \`styles: "css"\` flavor, or Tailwind utilities inline with \`styles: "tailwind"\` - set once via
 \`synthesisui init --styles tailwind\`). Import and render: \`import { Button } from "components/button"\`.
-The boundary: tokens are global (\`tokens.css\` + the \`data-ds\` root attribute, once per app);
-everything a component owns lives in its own folder.
+The boundary: everything a component owns lives in its own folder, and every value in it is a name
+YOUR code declares or the value itself - there is nothing global to set up.
 
 **A component's conditional classes are decided at the call site, not in the stylesheet.** A recipe
 carries the look of a state as a rule keyed on a data attribute (\`[data-size="lg"]\`), and the caller
@@ -623,80 +665,73 @@ ${meta.narrative}
 ${rulesNote}
 ## How to apply
 
-1. Import the system once in your project's global CSS, using a path **relative to that CSS
-   file** - from \`app/globals.css\` in a Next App Router project that means a leading \`../\`:
-   \`\`\`css
-   @import "../_synthesisui/ds/${slug}/tokens.css";
-   \`\`\`
-   (drop the \`../\` if your global CSS sits at the project root.)${hasTailwind
-        ? `\n   **Using Tailwind (this project's default)? You also need \`theme.css\` right after \`tokens.css\` -\n   without it the DS-backed utilities (\`bg-primary\`, \`p-md\`…) aren't generated and the UI renders\n   unstyled. See "Styling with Tailwind v4" below for the full import block.**`
-        : ""}
+**Nothing here is imported into your app.** \`_synthesisui/ds/${slug}/\` is the reference this guide,
+the check, the doctor and the MCP server read to interpret your design - your code never points at
+it, and nothing we write into this repository needs it at runtime.
 
-2. Wrap the tree that should use the system with the scope attribute:
-   \`\`\`html
-   <div data-ds="${slug}">…your UI here…</div>
-   \`\`\`
-   All \`--ds-*\` custom properties and \`.ds-*\` classes only apply inside that scope.
-   Applying \`data-ds="${slug}"\` at the app root (e.g. \`<body>\` or the root layout)
-   is the simplest choice - the whole app then wears the system.
-${hasAlt
-        ? `
-3. Light/dark: an ancestor with \`data-scheme="${altScheme}"\` switches the neutral roles to the opposite mode.
-   \`\`\`tsx
-   <div data-scheme="${altScheme}"><div data-ds="${slug}">…</div></div>
+1. Ask for a component and it arrives as YOUR code:
    \`\`\`
-   A theme toggle just adds/removes that attribute on the scope element:
-   \`\`\`tsx
-   root.toggleAttribute("data-scheme"); // present = ${altScheme}, absent = ${meta.scheme}
+   npx synthesisui component ${slug} <name>
    \`\`\`
-`
+   It lands in your components directory speaking the names your own code declares - or carrying the
+   value itself, where your code names none. No import, no scope attribute, nothing at runtime.
+
+2. Writing something by hand? Use the vocabulary below. Every name in it is a name **your own code
+   declares**, written exactly as you would write it.
+${hasAlt
+        ? `\n3. Light/dark: this system's roles have two readings, and a component that arrives from
+   \`component\` carries both. Which one shows is your app's own scheme switch - we do not add one.\n`
         : ""}${fontsSection}${depsSection}${hasTailwind
         ? `
 ## Styling with Tailwind v4 (preferred in this project)
 
-Import \`theme.css\` after \`tailwindcss\` and \`tokens.css\`:
-\`\`\`css
-@import "tailwindcss";
-@import "./_synthesisui/ds/${slug}/tokens.css";
-@import "./_synthesisui/ds/${slug}/theme.css";
-\`\`\`
-This maps the DS tokens onto Tailwind's theme, so inside \`[data-ds="${slug}"]\` you get utilities
-backed by the design system: \`bg-*\`/\`text-*\`/\`border-*\` (semantic colors), \`p-*\`/\`m-*\`/\`gap-*\`
-(spacing), \`rounded-*\`, \`shadow-*\`, \`font-*\` (families **and** weights), \`text-*\` (type scale), \`ease-*\`${seriesKeys.length > 0
-            ? `, \`bg-series-*\`/\`text-series-*\`/\`fill-series-*\` (data-viz series)`
-            : ""}.
+Your own \`@theme\` is what backs the utilities, and it is the one that decides. Where it declares a
+name, the utility already paints your value and it is the most readable code you can write; where it
+does not, write the value.
 
-**Prefer these utilities for layout and new composition** - they are this project's idiom and read
-far better than inline \`style\`. Reach for inline \`var(--ds-*)\` only when no utility fits.
+**Prefer utilities for layout and new composition** - they are this project's idiom and read far
+better than inline \`style\`.
 
 \`\`\`tsx
-// ✅ preferred - Tailwind utilities backed by the DS
-<main className="bg-canvas text-foreground p-2xl flex flex-col gap-md">
-  <button className="ds-button" data-intent="primary">Save</button>
+// preferred - your project's own utilities
+<main className="p-2xl flex flex-col gap-md">
+  <button className="rounded-md px-md py-2xs">Save</button>
 </main>
+\`\`\`
+
+To give a utility the system's value, declare the name in **your own** \`@theme\` - it is your
+stylesheet, your namespace, and nothing of ours is involved:
 
-// ❌ avoid - inline styles with raw var() when a utility exists
-<main style={{ background: "var(--ds-color-semantic-canvas)", padding: "var(--ds-spacing-2xl)" }}>
+\`\`\`css
+@theme {
+  --radius-md: <the value you want rounded-md to paint>;
+}
 \`\`\`
 
+Do that and \`synthesisui component\` starts writing \`rounded-md\` instead of the raw value, because
+the name now exists in your project.
+
 ---
 `
         : ""}
-This is **v${version}**. The stable entrypoints at \`_synthesisui/ds/${slug}/\` (the
-\`tokens.css\`/\`theme.css\` re-exports, plus \`.lock\`) always point at the active version - import
-those, not the versioned ones. The pinned files for this version - ${artifactList},
+This is **v${version}**. The pinned files for this version - ${artifactList},
 \`design-system.json\` (canonical source of truth), \`GUIDE.md\` (this file) - live in
-\`_synthesisui/ds/${slug}/v${version}/\`.
+\`_synthesisui/ds/${slug}/v${version}/\`, and they are OURS to read: the check, the doctor and the MCP
+server use them to interpret your design. Your app imports none of them.
 
 ---
 ${pagesSection}
 ## Building with the system
 
 **This system is for building real product UI** - pages, layouts, dashboards, whole flows.
-Compose the \`.ds-*\` recipes (and their parts) together with the DS-backed utilities to assemble
-actual screens. There is **no "samples only" rule**: build the real app. An
-\`app/synthesisui-samples/<component>/\` page is a fine *optional* scratch space to eyeball a single
-component, but it is never required.
+Bring the recipes in as YOUR code (\`npx synthesisui component ${slug} <name>\`) and compose them with
+your own utilities to assemble actual screens. There is **no "samples only" rule**: build the real
+app. An \`app/synthesisui-samples/<component>/\` page is a fine *optional* scratch space to eyeball a
+single component, but it is never required.
+
+The \`.ds-*\` class names below describe the recipe's SHAPE - which parts it has and which
+\`data-*\` each one takes. They are what the materialized component wears, and the stylesheet that
+declares them comes with it.
 
 ### Layout & composition
 The system defines the scale; these are sensible defaults for spending it:
@@ -728,10 +763,9 @@ part classes and their \`data-*\` are listed per component below. Example - a ta
 `
         : ""}
 ### Overlays & portals
-Dialogs, menus and toasts are often rendered through a portal at the end of \`<body>\` - **outside**
-your \`data-ds\` scope. Since \`.ds-*\`/\`--ds-*\` only resolve inside the scope, wrap any portalled UI
-in its own \`<div data-ds="${slug}"${hasAlt ? ` data-scheme="…"` : ""}>\`, or apply \`data-ds\` at the
-app root so everything (portals included) inherits it. Behavior (open/close, focus trap, positioning,
+Dialogs, menus and toasts are often rendered through a portal at the end of \`<body>\` - outside
+the tree they were written in. A component brought in by \`synthesisui component\` carries its own
+stylesheet and works anywhere, portal included. Behavior (open/close, focus trap, positioning,
 keyboard) is yours to wire - the system ships the **looks**, not the JavaScript.
 
 ### Interactive recipes - the behavior contract
@@ -756,34 +790,47 @@ styles it, you make it work.
 ## Rules (follow them when creating components)
 ${hasTailwind
         ? `
-- **Styling mechanism:** prefer Tailwind utilities backed by the DS (\`bg-primary\`, \`p-md\`,
-  \`font-display\`, \`font-medium\`, …) for layout and new composition, and reuse the \`.ds-*\` recipes
-  for components the DS already covers. Use inline \`style\` with \`var(--ds-*)\` only as a last resort.
-  The token names below are the source vocabulary - every utility derives from them.`
+- **Styling mechanism:** prefer your project's own Tailwind utilities for layout and new
+  composition, and bring the recipes in as code (\`synthesisui component ${slug} <name>\`) for the
+  components this system already covers. Where no utility fits, write the name from the vocabulary
+  below - it is a name your own code declares.`
         : ""}
-- **Always use semantic tokens**, never raw values nor primitives directly.
-  Color: \`var(--ds-color-semantic-<role>)\`${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}. The roles are: ${list(semanticRoles.map((r) => {
+- **Always use the system's vocabulary**, never raw values picked by eye. Every name below is a
+  name **your own code declares** - written exactly as you would write it. Nothing here comes from
+  a stylesheet of ours, and nothing needs one.
+  Color${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}: ${semanticRoles
+        .map((r) => {
         const theirs = theirRole(r);
-        return theirs === r ? r : `${r} (${theirs} in your code)`;
-    }))}.
-- Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly -
-  they feed the semantic roles.${namedColours.length > 0
-        ? `\n- **Yours by name** → \`var(--ds-color-<name>)\`: ${namedColours.length} colour${namedColours.length === 1 ? "" : "s"} your code names by PURPOSE rather than by step, so no scale could hold ${namedColours.length === 1 ? "it" : "them"} - ${list(namedColours.slice(0, 8))}${namedColours.length > 8 ? ", …" : ""}. These are yours: reach for them when the purpose matches, and prefer a semantic role when it does not.`
+        /** O papel com o nome que ELE dá a ele - e o parêntese só sai quando os dois diferem. */
+        const named = theirs === r ? `\`${r}\`` : `\`${r} (${theirs} in your code)\``;
+        const as = saysAs(`--ds-color-semantic-${kebab(r)}`);
+        return as ? `${named} → \`${as}\`` : named;
+    })
+        .join(", ")}.${namedColours.length > 0
+        ? `\n- **Yours by name**: ${namedColours.length} colour${namedColours.length === 1 ? "" : "s"} your code names by PURPOSE rather than by step, so no scale could hold ${namedColours.length === 1 ? "it" : "them"} - ${family("color", namedColours.slice(0, 8))}${namedColours.length > 8 ? ", …" : ""}. These are yours: reach for them when the purpose matches, and prefer a semantic role when it does not.`
         : ""}${seriesKeys.length > 0
-        ? `\n- Data-viz → \`var(--ds-color-series-<n>)\`${hasTailwind ? " (utility: `bg-series-<n>`/`text-series-<n>`/`fill-series-<n>`)" : ""}: categorical chart/series colors, ${seriesKeys.length} of them (${list(seriesKeys)}). Use them in order for multi-series charts; they re-paint with the system.`
+        ? `\n- Data-viz${hasTailwind ? " (utility: `bg-series-<n>`/`text-series-<n>`/`fill-series-<n>`)" : ""}: categorical chart/series colors, ${seriesKeys.length} of them - ${family("color-series", seriesKeys)}. Use them in order for multi-series charts; they re-paint with the system.`
         : ""}
-- Spacing → \`var(--ds-spacing-<key>)\`: ${list(Object.keys(foundations.spacing))}.
-- Radius → \`var(--ds-radius-<key>)\`: ${list(Object.keys(foundations.radius))}.
-- Shadow → \`var(--ds-shadow-<key>)\`: ${list(Object.keys(foundations.shadow))}.
+- Spacing → ${family("spacing", Object.keys(foundations.spacing))}.
+- Radius → ${family("radius", Object.keys(foundations.radius))}.
+- Shadow → ${family("shadow", Object.keys(foundations.shadow))}.
 - Typography: families ${familySlots(foundations.typography.families)
-        .map((slot) => `\`${payload.fontSeam?.[slot] ?? `${FAMILY_SEAM_PREFIX}${slot}`}\` (${foundations.typography.families[slot]})`)
+        .map((slot) => {
+        const as = saysAs(`${FAMILY_SEAM_PREFIX}${kebab(slot)}`);
+        const face = foundations.typography.families[slot];
+        return as ? `\`${slot}\` → \`${as}\` (${face})` : `\`${slot}\` (${face})`;
+    })
         .join(", ")};
   weights${hasTailwind ? " (utility: `font-<key>`)" : ""}: ${list(weights)};
-  scale \`--ds-typography-scale-<key>-font-size\`${hasTailwind ? " (utility: `text-<key>`)" : ""}: ${list(Object.keys(foundations.typography.scale))}.
-- Motion: durations \`--ds-motion-durations-<key>\` (${list(Object.keys(motion.durations))}) and
-  easings \`--ds-motion-easings-<key>\` (${list(Object.keys(motion.easings))}). Use them on
-  \`transition\` (e.g. \`transition: color var(--ds-motion-durations-fast) var(--ds-motion-easings-standard)\`)
-  so timing stays on-brand. For ANIMATION, this system ships a named vocabulary - see
+  scale${hasTailwind ? " (utility: `text-<key>`)" : ""}: ${Object.keys(foundations.typography.scale)
+        .map((k) => {
+        const as = saysAs(`--ds-typography-scale-${kebab(k)}-font-size`);
+        return as ? `\`${k}\` → \`${as}\`` : `\`${k}\``;
+    })
+        .join(", ")}.
+- Motion: durations ${family("motion-durations", Object.keys(motion.durations))}
+  and easings ${family("motion-easings", Object.keys(motion.easings))}. Use them on
+  \`transition\` so timing stays on-brand. For ANIMATION, this system ships a named vocabulary - see
   **Motion vocabulary** below; never hand-roll \`@keyframes\` or raw durations.
 - When **creating a new component** the DS does not cover yet: compose it from these semantic
   tokens to inherit the system's identity; do not invent colors/measures outside the scale.
@@ -817,7 +864,8 @@ tell the person what you chose from the vocabulary instead.`
 
 ## Ready-made components
 
-Each recipe becomes a \`.ds-<name>\` class (inside the \`[data-ds="${slug}"]\` scope). Variants are
+Each recipe has a \`.ds-<name>\` class - the SHAPE it wears when \`synthesisui component\` writes it
+into your project, with the stylesheet that declares it alongside. Variants are
 \`data-<axis>="<option>"\` attributes; states (hover/focus/active/disabled) ship in the CSS;
 multi-part components expose \`.ds-<name>-<part>\` classes (listed under each).
 
@@ -832,7 +880,7 @@ A small gamification library the AI advisor (\`synthesisui advise\`) can propose
 \`.ds-<name>\` recipe shape as the components above, token-only so they wear the system. Use them
 **only where they fit the product** (progress, retention, recognition); they're a library to compose
 from, not a default - and lean against over-gamifying a serious B2B product. Each is a \`.ds-<name>\`
-class inside the \`[data-ds="${slug}"]\` scope; multi-part ones expose \`.ds-<name>-<part>\`.
+recipe; multi-part ones expose \`.ds-<name>-<part>\`.
 
 ${blockLines.join("\n\n")}
 `

package/dist/install-marks.js

@@ -235,7 +235,7 @@
  * chama `wireAgent`, então rodar o comando é o caminho de volta - e ele só alarga a string que era
  * nossa, nunca um filtro que uma pessoa escreveu.
  */
-export const MATERIALISER_SINCE = "0.16.421";
+export const MATERIALISER_SINCE = "0.16.423";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -343,8 +343,8 @@ export const MATERIALISER_SINCE = "0.16.421";
  * A frase viaja ao lado da versão porque as duas são uma coisa só: quem move a marca troca a
  * explicação no mesmo lugar, em vez de deixar o CI citando a causa da marca anterior.
  */
-export const COUNTED_DIFFERENTLY_SINCE = "0.16.421";
-export const COUNTED_DIFFERENTLY = "this run counts the utilities of your own theme - that version counted only `var(--token)`";
+export const COUNTED_DIFFERENTLY_SINCE = "0.16.422";
+export const COUNTED_DIFFERENTLY = "this run counts a value as named only when YOUR code names it - that version also counted the ones only the system named";
 /**
  * 0.16.408 -> 0.16.413 em 10/09: o hook passa a DIZER o valor que nada nomeia. Ele silenciava toda
  * deriva sem token de destino - a decisão estava escrita como "não vale interromper, porque o único
@@ -366,7 +366,7 @@ export const COUNTED_DIFFERENTLY = "this run counts the utilities of your own th
  * utility, um arquivo escrito inteiro no vocabulário do sistema recebia zero. A contagem em si é a
  * outra marca - ver `COUNTED_DIFFERENTLY_SINCE`, que sobe no mesmo diff.
  */
-export const CHECKER_SINCE = "0.16.421";
+export const CHECKER_SINCE = "0.16.422";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/local-edits.js

@@ -0,0 +1,257 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** A forma mínima que faz de um objeto um design system - abaixo disto não há o que comparar. */
+function shapeOf(value) {
+    if (!value || typeof value !== "object")
+        return "it is not an object";
+    const doc = value;
+    if (!doc.meta || typeof doc.meta !== "object")
+        return "it has no `meta` - a design system always carries its name and slug";
+    if (!doc.foundations || typeof doc.foundations !== "object")
+        return "it has no `foundations` - a design system always carries its tokens";
+    return null;
+}
+async function readDocument(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            why: error instanceof Error ? error.message : "it is not valid JSON",
+        };
+    }
+    const wrong = shapeOf(parsed);
+    if (wrong)
+        return { ok: false, why: wrong };
+    return { ok: true, document: parsed };
+}
+/**
+ * QUAL VERSÃO ESTÁ MATERIALIZADA NESTE REPOSITÓRIO - a que o `.lock` registra.
+ *
+ * Ler a pasta `v*` mais alta seria adivinhar: um `add --version N` deixa as duas no disco, e o
+ * `.lock` é o que diz qual delas o repositório está usando. `null` quando não há install.
+ */
+export async function installedVersion(root, slug) {
+    try {
+        const raw = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8");
+        const lock = JSON.parse(raw);
+        return typeof lock.version === "number" ? lock.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** O par que a comparação precisa: o que foi instalado, e o que está no disco agora. */
+export async function readInstalledPair(root, slug, version) {
+    const dir = join(root, "_synthesisui", "ds", slug, `v${version}`);
+    const local = await readDocument(join(dir, "design-system.json"));
+    if (local === null)
+        return { kind: "not-installed" };
+    if (!local.ok)
+        return {
+            kind: "unreadable",
+            where: join(dir, "design-system.json"),
+            why: local.why,
+        };
+    const installed = await readDocument(join(dir, ".installed.json"));
+    if (installed === null)
+        return {
+            kind: "no-baseline",
+            /**
+             * O CAMINHO DE SAÍDA AVISA DO RISCO ANTES DO COMANDO.
+             *
+             * `add` reescreve `design-system.json` sem comparar nada. Mandar rodá-lo sem dizer isso
+             * apagaria, em silêncio, exatamente a edição que este recurso existe para preservar - e a
+             * pessoa teria seguido o passo que a plataforma recomendou.
+             */
+            why: `this install predates the file that tracks your edits, and \`add\` rewrites design-system.json. If you already edited it, copy it first (cp _synthesisui/ds/${slug}/v<n>/design-system.json /tmp/${slug}-before-add.json), then run \`npx synthesisui@latest add ${slug}\` once - every edit made after that comes up with the next sync.`,
+        };
+    if (!installed.ok)
+        return {
+            kind: "unreadable",
+            where: join(dir, ".installed.json"),
+            why: installed.why,
+        };
+    return { kind: "pair", installed: installed.document, local: local.document };
+}
+/** Achata fundação e motion em `caminho → valor`, na mesma gramática do documento. */
+function flatten(value, prefix, into) {
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, inner] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (typeof inner === "string" || typeof inner === "number")
+            into.set(path, String(inner));
+        else
+            flatten(inner, path, into);
+    }
+}
+/**
+ * O QUE NÃO VIAJA, DITO EM VOZ ALTA - lei 8, e a lista é curta de propósito.
+ *
+ * `meta` é a identidade do sistema (nome, slug, tagline): mudá-la é ato dela na plataforma, não
+ * do agente dele. `philosophy` e `analyses` são texto que a plataforma escreve e nenhum prompt
+ * pede para editar. Os três ficam fora porque não são decisão do código dele - e é por isso que
+ * a ausência deles aqui é uma escolha, e não um esquecimento.
+ */
+export const NOT_FROM_HIS_FILES = ["meta", "philosophy", "analyses"];
+const RECIPE_MAPS = [
+    ["components", "component"],
+    ["blocks", "block"],
+    ["layouts", "layout"],
+    ["charts", "chart"],
+];
+/**
+ * A PROCEDÊNCIA NÃO É UM TOKEN, e o mesmo defeito já custou uma sessão do outro lado.
+ *
+ * `foundations.source` guarda quem escreveu cada caminho. Sem esta linha, um carimbo mudado por
+ * um comando nosso apareceria como "o agente dele trocou um valor de design".
+ */
+function tokensOf(doc) {
+    const out = new Map();
+    const { source: _source, ...rest } = doc.foundations;
+    flatten(rest, "", out);
+    /**
+     * E TODO EIXO DE RAIZ QUE NÃO É RECEITA, varrido pelo que o documento TEM - e não por uma
+     * lista escrita à mão.
+     *
+     * A primeira escrita enumerava `foundations` e `motion`, e deixava de fora `icons` e
+     * `globals` - este último carrega a folha de projeto inteira, 107 declarações num cliente
+     * real. O agente editava, o `sync` dizia "nothing new", e a alteração morria no disco.
+     * Varrer o que existe faz um eixo NOVO do contrato entrar sozinho, em vez de esperar alguém
+     * lembrar.
+     */
+    const root = doc;
+    const recipes = new Set(RECIPE_MAPS.map(([key]) => key));
+    for (const key of Object.keys(root)) {
+        if (key === "foundations")
+            continue;
+        if (recipes.has(key))
+            continue;
+        if (NOT_FROM_HIS_FILES.includes(key))
+            continue;
+        flatten(root[key], key, out);
+    }
+    return out;
+}
+function fileOf(recipe) {
+    return recipe?.source?.file;
+}
+/**
+ * O QUE MUDOU ENTRE O QUE FOI INSTALADO E O QUE ESTÁ NO DISCO.
+ *
+ * Puro sobre os dois documentos. Uma receita conta como UMA alteração, e não uma por declaração:
+ * o que o cliente lê no terminal é "o agente mexeu no Button", e a lista de declarações mora no
+ * documento que sobe junto.
+ */
+export function localEdits(installed, local) {
+    const out = [];
+    const was = tokensOf(installed);
+    const now = tokensOf(local);
+    for (const path of [...new Set([...was.keys(), ...now.keys()])].sort()) {
+        const from = was.get(path);
+        const to = now.get(path);
+        if (from === to)
+            continue;
+        out.push({
+            what: path,
+            of: "token",
+            kind: from === undefined ? "added" : to === undefined ? "removed" : "changed",
+            ...(from !== undefined ? { from } : {}),
+            ...(to !== undefined ? { to } : {}),
+        });
+    }
+    for (const [key, of_] of RECIPE_MAPS) {
+        const before = installed[key];
+        const after = local[key];
+        const names = [
+            ...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]),
+        ].sort();
+        for (const name of names) {
+            const from = before?.[name];
+            const to = after?.[name];
+            if (from === undefined && to === undefined)
+                continue;
+            if (from !== undefined && to !== undefined) {
+                if (JSON.stringify(from) === JSON.stringify(to))
+                    continue;
+                const file = fileOf(to) ?? fileOf(from);
+                out.push({
+                    what: name,
+                    of: of_,
+                    kind: "changed",
+                    ...(file ? { file } : {}),
+                });
+                continue;
+            }
+            const file = fileOf(to ?? from);
+            out.push({
+                what: name,
+                of: of_,
+                kind: from === undefined ? "added" : "removed",
+                ...(file ? { file } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * QUANTAS LINHAS O TERMINAL NOMEIA ANTES DE DIZER QUANTAS SOBRARAM.
+ *
+ * Doze é o que cabe numa tela sem rolagem depois do resto da saída do `sync`, e o que não couber
+ * é DITO - uma lista cortada em silêncio faz doze alterações parecerem doze quando são quarenta.
+ */
+const NAMED = 12;
+/**
+ * O QUE O `sync` DIZ SOBRE O QUE ELE ENCONTROU NOS ARQUIVOS - nunca um "ok" mudo, e nunca uma
+ * afirmação de sucesso antes de o servidor responder.
+ *
+ * A primeira escrita dizia *"N changes from your files WENT UP"*, e ela era montada antes do
+ * envio: quando o servidor recusava, a saída afirmava sucesso numa linha e fracasso na seguinte,
+ * na mesma tela. Quem lê rápido carrega a primeira. Esta frase relata o que foi ENCONTRADO; quem
+ * diz que chegou é `landedLine`, depois da resposta.
+ */
+export function sentLine(edits, slug) {
+    if (edits.length === 0)
+        return `nothing new in ${slug} - the design system on this machine matches what the platform has`;
+    const head = `${edits.length} change${edits.length === 1 ? "" : "s"} found in your files, from ${slug}:`;
+    const lines = edits.slice(0, NAMED).map((edit) => {
+        const where = edit.file ? ` · ${edit.file}` : "";
+        const move = edit.from !== undefined && edit.to !== undefined
+            ? ` ${edit.from} → ${edit.to}`
+            : edit.kind === "added"
+                ? " (new)"
+                : edit.kind === "removed"
+                    ? " (gone)"
+                    : "";
+        return `      ${edit.what}${move}${where}`;
+    });
+    const rest = edits.length > NAMED ? [`      and ${edits.length - NAMED} more`] : [];
+    return [head, ...lines, ...rest].join("\n");
+}
+/**
+ * DEPOIS DE SUBIR, O BASELINE PASSA A SER O QUE ESTÁ NO DISCO - a metade que fecha o ciclo.
+ *
+ * Sem isto, todo `sync` reenviaria a mesma alteração para sempre e o documento na plataforma
+ * ganharia uma revisão nova a cada rodada, sem nada ter mudado. É a outra metade de A4, e ela
+ * mora aqui - e não no corpo do comando - para poder ser exercida por spec sem subir nada.
+ *
+ * SÓ DEPOIS DE O SERVIDOR TER ACEITADO: uma recusa mantém o baseline velho, para a próxima
+ * rodada tentar de novo em vez de esquecer o que ele fez.
+ */
+/** E a confirmação, depois de o servidor ter aceitado - a única frase no passado. */
+export function landedLine(applied, slug) {
+    return `${applied} change${applied === 1 ? "" : "s"} from your files went up to ${slug}`;
+}
+export async function settleBaseline(root, slug, version, document) {
+    await writeFile(join(root, "_synthesisui", "ds", slug, `v${version}`, ".installed.json"), `${JSON.stringify(document)}\n`, "utf8");
+}