synthesisui 0.16.235 → 0.16.239

package/dist/claude-md.js

@@ -186,9 +186,9 @@ session. It costs nothing when nothing changed: the tool holds both versions and
 refuses politely when there is nothing to refresh, so calling it is cheaper than
 deciding whether to.
 
-It re-measures this repo with the current reader, reuses the reading that was already
-authored, and sends it - a newer reader sees styles the old one could not, and until
-it runs, this project's system is missing them.
+It re-measures this repo with the current reader, reuses what was already written
+about this app, and sends it - a newer reader sees styles the old one could not, and
+until it runs, this project's system is missing them.
 
 It never asks anyone anything, and it never overwrites a recipe a person wrote on
 the screen: when a send would rewrite one, it refuses and names them. If it says
@@ -196,8 +196,8 @@ nothing changed, nothing changed - carry on.
 
 **And when you describe this system, open with the age of the measurement:** the
 \`ledger.cli\` and the date in \`_synthesisui/census.json\`. A long, correct report
-about a census taken by an older reader is the worst way to be right - every absence
-in it may have been filled since, and the reader who trusts it has no way to know.
+about a measurement taken by an older reader is the worst way to be right - every
+absence in it may have been filled since, and the reader who trusts it has no way to know.
 
 **And if it says the design system needs updating, do these three things in order:**
 say the one line, ask, and run it.
@@ -334,7 +334,8 @@ extend that. The person who asked you for a feature should never have to know th
 names or type them; finding the right component is your job, not theirs.
 
 Overriding a style a component already sets just works - write
-\`className="text-info"\`, with no \`!\`. The generated components resolve your class
+\`className="text-<role>"\` with one of this system's own colour roles (the GUIDE
+lists them), with no \`!\`. The generated components resolve your class
 against their own, so the last one written wins, which is what the call site reads like.
 If an override is ignored, that component predates the resolver: regenerate it with
 \`npx synthesisui@latest component <slug> <name>\` rather than reaching for \`!\`.

package/dist/commands/add.js

@@ -250,15 +250,13 @@ export async function add(slug, opts) {
         await writeFile(join(slugDir, "requires.json"), `${JSON.stringify(required, null, 2)}\n`, "utf8");
     }
     /** A filosofia continua sendo CONTADA na saída, e ela vive no documento - ver abaixo. */
-    const philosophy = payload.document.philosophy;
-    const sections = philosophy?.sections ?? [];
+    const voice = payload.voice ?? { hasContext: false, sections: 0 };
     /**
-     * 5c. A FILOSOFIA NÃO É MATERIALIZADA - ela já está aqui.
-     *
-     * `philosophy` é campo do DOCUMENTO versionado (`design-system.ts`), e o `design-system.json`
-     * escrito no passo 2 a carrega inteira. O `philosophy.md` era uma segunda cópia do mesmo dado, no
-     * mesmo commit, que só era reescrita no upgrade seguinte - dois caminhos para uma verdade é como
-     * um deles começa a discordar do outro. O `system_doctrine` lê do documento.
+     * 5c. A VOZ NÃO É MATERIALIZADA - nem no `.md` (aposentado acima) nem no
+     * `design-system.json` (R2, 16/08: o payload viaja sem `philosophy`). Ela
+     * mora na plataforma e o `system_doctrine` a busca servida - sempre a
+     * versão atual, nada em texto plano no repo. As REGRAS continuam locais
+     * (`doctrine.json`): o doctor e o hook precisam delas offline.
      */
     // 6. discovery by the agent
     const claudeMd = await syncClaudeMd(projectRoot);
@@ -288,8 +286,8 @@ export async function add(slug, opts) {
      */
     const doctrine = [
         ...(rules.length > 0 ? [`${rules.length} rule(s)`] : []),
-        ...(sections.length > 0 || philosophy?.context
-            ? [`${sections.length} section(s) of philosophy`]
+        ...(voice.sections > 0 || voice.hasContext
+            ? [`the voice (${voice.sections} section(s), served from the platform)`]
             : []),
     ];
     if (doctrine.length > 0)

package/dist/commands/adopt.js

@@ -134,6 +134,14 @@ async function findTokens(root, only) {
 /** The contract. Names THEIR tokens - there is no translation layer. */
 function guide(name, slug, tokens) {
     const lines = [...tokens.entries()].map(([k, v]) => `  ${k}: ${v};`);
+    /**
+     * O EXEMPLO É UM TOKEN REAL DELE. A promessa três linhas abaixo é "YOUR tokens, under YOUR
+     * names" - e o exemplo inventava `--<slug>-color-primary`, um prefixo derivado por nós + um papel
+     * nosso, que pode não existir no CSS de ninguém. O primeiro token de cor DELE cumpre a promessa.
+     */
+    const example = [...tokens.entries()].find(([, v]) => /^#|^(rgb|hsl|oklch|color)\(/i.test(v.trim()))?.[0] ??
+        [...tokens.keys()][0] ??
+        `--${slug}-color-primary`;
     return `# ${name} - the contract your agent follows
 
 Adopted from this repository by \`synthesisui adopt\`. These are YOUR tokens,
@@ -145,7 +153,7 @@ When writing or editing UI in this project, use these custom properties.
 Do not write raw colours, spacings or radii that a token already covers.
 
     ✗  background: #3b82f6
-    ✓  background: var(--${slug}-color-primary)
+    ✓  background: var(${example})
 
 If a value has no token, say so instead of inventing one silently - a new
 token is a decision for a person to make.

package/dist/commands/component.js

@@ -59,14 +59,21 @@ export async function component(slug, name, opts) {
     if (!SAFE_NAME.test(res.name)) {
         throw new RegistryError(`Registry returned an unsafe component name.`);
     }
-    const dir = join(root, "_synthesisui", "ds", slug, "components");
-    await mkdir(dir, { recursive: true });
-    await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
-    await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
-    console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
+    // R3 (dono, 16/08): as cópias .json/.css em _synthesisui só nascem quando
+    // são o PRODUTO do comando - `--artifacts-only` e targets não-Next. Quando
+    // o .tsx é materializado logo abaixo, ninguém as lê depois (medido na
+    // auditoria de 16/08), e cada arquivo a mais no repo dele é superfície.
+    const config = await readProjectConfig(root);
+    const artifactsAreTheProduct = opts.artifactsOnly === true || config.target !== "next";
+    if (artifactsAreTheProduct) {
+        const dir = join(root, "_synthesisui", "ds", slug, "components");
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
+        await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
+        console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
+    }
     // 2. YOUR component - a real, importable `export function <Pascal>()` in the
     //    project's flavor (config: styles css|tailwind), under componentsDir.
-    const config = await readProjectConfig(root);
     const wantInteractive = opts.interactive && hasInteractiveTemplate(res.name);
     if (!opts.artifactsOnly && config.target === "next") {
         /**

package/dist/commands/doctor.js

@@ -1179,17 +1179,21 @@ export async function doctor(opts) {
             const w = Math.max(...repeats.map((r) => r.literal.length));
             for (const r of repeats) {
                 const where = `${r.count}\u00d7 in ${r.files} file${r.files === 1 ? "" : "s"}`;
-                const near = nameToWrite(r) ? null : nearestToken(table, r.literal);
+                const near = nameToWrite(r)
+                    ? null
+                    : nearestToken(table, r.literal, r.kind);
                 /**
                  * COINCIDÊNCIA NÃO É RESPOSTA - ver `crossFamily` em `scan.ts`. Para aquele `kind` o
                  * sistema não tem nome; o valor mora noutra família, e dizer só a seta afirma o contrário.
+                 * MAS quando o REPO DELE nomeia o valor (`theirToken`), esse nome vale - `apply-fix.ts:140`
+                 * e a classificação de sugestão já tratam assim; só a impressão tinha ficado para trás.
                  */
-                const named = r.crossFamily
+                const named = r.crossFamily && !r.theirToken
                     ? `  → no ${r.kind} named for it · the value lives as ${r.token}`
                     : nameToWrite(r)
                         ? `  → ${nameToWrite(r)}`
                         : near
-                            ? `  → nearest is ${near.name} (${near.value})`
+                            ? `  → nearest is ${near.theirs ?? near.name} (${near.value})`
                             : "";
                 say(`      ${r.literal.padEnd(w)}  ${where}${named}`);
             }
@@ -1205,13 +1209,15 @@ export async function doctor(opts) {
             for (const x of shown) {
                 // A dead end with a neighbour is not a dead end. Only for lengths -
                 // "nearly the same blue" is the guess this tool must never make.
-                const near = nameToWrite(x) ? null : nearestToken(table, x.literal);
-                const named = x.crossFamily
+                const near = nameToWrite(x)
+                    ? null
+                    : nearestToken(table, x.literal, x.kind);
+                const named = x.crossFamily && !x.theirToken
                     ? `→ no ${x.kind} named for it · the value lives as ${x.token}`
                     : nameToWrite(x)
                         ? `→ ${nameToWrite(x)}`
                         : near
-                            ? `→ nearest is ${near.name} (${near.value})`
+                            ? `→ nearest is ${near.theirs ?? near.name} (${near.value})`
                             : "→ no token holds this value yet";
                 say(`      ${String(x.line).padStart(4)}  ${x.literal}  ${named}`);
             }
@@ -1308,13 +1314,14 @@ export async function doctor(opts) {
     if (frozen.length > 0) {
         say(section("These will not follow your other scheme"));
         say(body(frozen.length === 1
-            ? "One recipe names a primitive where a SURFACE role of yours holds the same value."
-            : `${frozen.length} recipes name a primitive where a SURFACE role of yours holds the same value.`));
+            ? "One recipe pins a fixed shade where a surface colour of this system holds the same value."
+            : `${frozen.length} recipes pin a fixed shade where a surface colour of this system holds the same value.`));
         say("");
         for (const f of frozen) {
             say(body(`ds-${f.component} · ${f.where}`));
             say(`          binds ${f.wrote}`);
-            say(`          {color.semantic.${f.role}} holds that, and becomes ${f.becomes}`);
+            /** A grafia que EXISTE no repo dele - o CSS compilado carrega esta variável; `{color.semantic.*}` é formato nosso e não sai. */
+            say(`          var(--ds-color-semantic-${f.role}) holds that, and becomes ${f.becomes}`);
             say("");
         }
         say(body("The value resolves and the CSS compiles, so nothing"));
@@ -1557,7 +1564,7 @@ export async function doctor(opts) {
         });
     }
     for (const r of unnamed.slice(0, migrating ? 3 : 2)) {
-        const near = nearestToken(table, r.literal);
+        const near = nearestToken(table, r.literal, r.kind);
         plan.push({
             rank: migrating ? 3 : 4,
             /**
@@ -1567,7 +1574,7 @@ export async function doctor(opts) {
              * fila da anterior: aquela tem nome esperando, esta precisa de um.
              */
             what: near
-                ? `${r.literal} - name it, or snap to ${near.name}`
+                ? `${r.literal} - name it, or snap to ${near.theirs ?? near.name}`
                 : r.crossFamily
                     ? `${r.literal} - no ${r.kind} named for it, and the value lives as ${r.token} in another family`
                     : `${r.literal} - no name for it, here or in your CSS`,
@@ -1753,7 +1760,8 @@ export async function doctor(opts) {
         const verdict = compareToBaseline(d, base, {
             ...(relScopes.length ? { scope: relScopes.join(",") } : {}),
         });
-        console.log(section(verdict.worse ? "Drift went up" : "Ratchet"));
+        /** "Drift" é a nossa palavra e não sai (ver a tradução da seção principal); aqui idem. */
+        console.log(section(verdict.worse ? "Hand-written values went up" : "Holding the line"));
         for (const line of describeVerdict(verdict))
             console.log(body(line));
         if (verdict.worse)

package/dist/commands/gaps.js

@@ -22,7 +22,7 @@ export async function gaps(opts) {
     const raw = await readFile(path, "utf8").catch(() => null);
     console.log(section("What this pipeline did not read"));
     if (!raw) {
-        console.log(body(`No census at ${path}. Run \`synthesisui import --dry\` first - that is what measures your files, and it writes the census there.`));
+        console.log(body(`No measurement at ${path}. Run \`synthesisui import --dry\` first - that is what measures your files, and it writes the result there.`));
         return;
     }
     let ledger;
@@ -39,7 +39,7 @@ export async function gaps(opts) {
      * contar.
      */
     if (!ledger) {
-        console.log(body(`This census was written by a CLI that did not count style fragments yet, so the numbers do not exist rather than being zero. Run \`synthesisui import --dry\` again with ${opts.cli} to measure.`));
+        console.log(body(`This measurement was written by a tool version that did not count style fragments yet, so the numbers do not exist rather than being zero. Run \`synthesisui import --dry\` again with ${opts.cli} to measure.`));
         return;
     }
     for (const line of describeTriage(triageLedger(ledger, opts.cli)))

package/dist/commands/generate.js

@@ -55,17 +55,21 @@ export async function generate(description, opts) {
     }
     console.log(`→ generating a component for "${slug}" at ${base} …`);
     const res = await postGenerate(base, { slug, description, name: opts.name });
-    const dir = join(root, "_synthesisui", "ds", slug, "generated");
-    await mkdir(dir, { recursive: true });
-    await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
-    await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
     const tries = `${res.tries} ${res.tries === 1 ? "try" : "tries"}`;
     console.log(`✓ ${res.name} generated (${res.model}, ${tries})`);
-    console.log(`  → _synthesisui/ds/${slug}/generated/${res.name}.{json,css}`);
     // Materialize YOUR component (.tsx) too - the SAME codegen `component` uses -
     // so a generated component is as usable as a brought-in one, not just a
     // recipe you have to wire by hand.
     const config = await readProjectConfig(root);
+    // R3 (dono, 16/08): as cópias .json/.css só quando são o produto - num
+    // target não-Next o .tsx abaixo não nasce, e aí elas são a entrega.
+    if (config.target !== "next") {
+        const dir = join(root, "_synthesisui", "ds", slug, "generated");
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
+        await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
+        console.log(`  → _synthesisui/ds/${slug}/generated/${res.name}.{json,css}`);
+    }
     let materialized = false;
     if (config.target === "next") {
         const version = await readActiveVersion(root, slug);

package/dist/commands/import.js

@@ -3113,7 +3113,7 @@ export async function runImport(opts) {
     if (creds && !sameRegistry(creds.registry, base)) {
         console.log("");
         console.log(body(`You are logged in to ${paint.strong(creds.registry ?? "another registry")}, and this would go to ${paint.strong(base)}.`));
-        console.log(body("The census is on disk. Either name the one you meant:"));
+        console.log(body(`Your measurement is saved at ${out}. Either name the one you meant:`));
         console.log("");
         console.log(body(`    synthesisui import --census ${out} --registry ${creds.registry}`));
         console.log(body("or log in to this one:"));
@@ -3143,7 +3143,7 @@ export async function runImport(opts) {
         // which of the two it was (dono, 31/07). A stale token gets past the
         // `readToken` guard above and only fails here.
         if (res?.status === 401) {
-            console.log(body("Your session has expired. The census is on disk."));
+            console.log(body(`Your session has expired. Your measurement is saved at ${out}.`));
             console.log("");
             console.log(body(`    ${paint.strong("synthesisui login")}`));
             console.log(body(`    synthesisui import --census ${out}${chosen ? ` --name "${chosen}"` : ""}`));
@@ -3152,7 +3152,7 @@ export async function runImport(opts) {
         }
         console.log(body(res
             ? `The registry refused it (HTTP ${res.status})${detail ? `: ${detail}` : "."}`
-            : "Could not reach the registry. The census is on disk - try again later."));
+            : `Could not reach the registry. Your measurement is saved at ${out} - try again later.`));
         console.log("");
         return;
     }

package/dist/commands/mcp.js

@@ -6,7 +6,7 @@ import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
-import { nearestToken, tokenFor } from "../doctor/tokens.js";
+import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
 import { repoStateOf } from "../repo-state.js";
 import { component } from "./component.js";
 import { loadSystem, walkAll } from "./doctor.js";
@@ -109,6 +109,25 @@ const TOOLS = [
             required: ["name"],
         },
     },
+    {
+        name: "playbook",
+        description: "The skill playbooks (init, import, adapt) - SERVED, not shipped, so they are always current and your context only carries the step you are on. Call with { skill } to get the framing and a table of contents; then fetch ONLY the chapter for your current step with { skill, section }. Never fetch more than the step needs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                skill: {
+                    type: "string",
+                    enum: ["init", "import", "adapt"],
+                    description: "Which playbook.",
+                },
+                section: {
+                    type: "string",
+                    description: "A chapter id from the toc. Omit to get the framing + toc.",
+                },
+            },
+            required: ["skill"],
+        },
+    },
     {
         name: "recipe_vocabulary",
         description: "What a recipe CAN hold: every state that compiles, every preview form, the floor per kind, and the rules a media region needs. Call this BEFORE writing a recipe, not after - the reader that skipped it sent a `dark:` inside a variant and a state the compiler cannot spell, and both were dropped in silence. Served from the catalogue, so it grows as the contract grows.",
@@ -271,12 +290,29 @@ async function findToken(root, value) {
     const { table } = await loadSystem(root);
     if (table.byName.size === 0)
         return "No design system installed here.";
+    /**
+     * O NOME DELE PRIMEIRO, como no doctor (`nameToWrite`): `loadSystem` já devolve a tabela COM os
+     * aliases dele (`withTheirNames`) e este era o único leitor que nunca os consultava. Sem o `kind`
+     * do contexto, a busca varre as famílias - um alias em qualquer uma delas é o nome que o repo
+     * DELE dá àquele valor.
+     */
+    const theirNameFor = (v) => {
+        const norm = normalizeValue(v, table.rootPx);
+        for (const [key, name] of table.aliases)
+            if (key.endsWith(`:${norm}`))
+                return name;
+        return null;
+    };
     const exact = tokenFor(table, value);
-    if (exact)
-        return `${value} is ${exact} in this system. Use var(${exact}).`;
+    if (exact) {
+        const shown = theirNameFor(value) ?? exact;
+        return `${value} is ${shown} in this project. Use var(${shown}).`;
+    }
     const near = nearestToken(table, value);
-    if (near)
-        return `No token holds ${value}. The closest is ${near.name} at ${near.value}. If that is what you meant, use it - if it genuinely is not, say so rather than inventing a token.`;
+    if (near) {
+        const shown = theirNameFor(near.value) ?? near.name;
+        return `No token holds ${value}. The closest is ${shown} at ${near.value}. If that is what you meant, use it - if it genuinely is not, say so rather than inventing a token.`;
+    }
     // Same words the managed block uses. A refusal is only useful if it is the
     // same refusal every time.
     return `No token in this system holds ${value}, and nothing is close. Do NOT invent one. Say which value you need and what you would call it, and let a person decide.`;
@@ -297,18 +333,55 @@ async function findToken(root, value) {
  * palavra que a pessoa já tem. Sem rede, a doutrina responde igual e a checagem é que se cala: o
  * dado é local justamente para não depender de servidor nenhum.
  */
+/** A voz do sistema, servida da plataforma - ver o comentário no chamador. */
+async function fetchVoice(root) {
+    const slug = await installedSlug(root);
+    const token = await readToken();
+    if (!slug || !token)
+        return { kind: "unreachable" };
+    const res = await fetch(`${resolveRegistry()}/api/registry/ds/${slug}?voice=1`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null);
+    if (!res?.ok)
+        return { kind: "unreachable" };
+    const body = (await res.json().catch(() => null));
+    if (!body)
+        return { kind: "unreachable" };
+    return {
+        kind: "ok",
+        voice: {
+            context: body.context ?? undefined,
+            sections: body.sections ?? [],
+        },
+    };
+}
 async function systemDoctrine(root) {
     const { documents, doctrines } = await loadSystem(root);
     const rules = doctrines.flatMap((d) => d.rules);
     const parts = [];
     const pinned = doctrines[0]?.version;
-    for (const doc of documents) {
-        const p = doc.philosophy;
-        if (p?.context)
+    /**
+     * A VOZ É SERVIDA, NÃO LIDA DO DISCO (R2, dono 16/08). As REGRAS continuam
+     * locais - o doctor e o hook precisam delas offline, e essa decisão está
+     * declarada três vezes. A voz nunca foi lida por nenhum loop local: só esta
+     * ferramenta a renderiza, e ela agora pergunta à plataforma - sempre a
+     * versão atual, e nada dela em texto plano no repo. Sem rede, as regras
+     * respondem igual e a voz se declara indisponível em vez de sumir calada.
+     *
+     * Installs antigos (design-system.json com `philosophy` dentro) continuam
+     * funcionando: o disco é o fallback quando a rede não responde.
+     */
+    const localVoice = documents.map((doc) => doc.philosophy ?? {});
+    const served = await fetchVoice(root);
+    const voices = served.kind === "ok"
+        ? [served.voice]
+        : localVoice.filter((p) => p.context || (p.sections?.length ?? 0) > 0);
+    for (const p of voices) {
+        if (p.context)
             parts.push(`## What this product is\n\n${p.context}`);
-        for (const sec of p?.sections ?? [])
+        for (const sec of p.sections ?? [])
             parts.push(`## ${sec.title}\n\n${sec.body}`);
     }
+    if (served.kind === "unreachable" && voices.length === 0)
+        parts.push("## Voice\n\nThe voice is served from the platform and could not be reached right now. The rules above still apply in full - build with them, and fetch the voice again before writing user-facing copy.");
     if (rules.length === 0 && parts.length === 0)
         return "This system carries no rules and no philosophy yet. Nothing here overrides your judgement - build with its tokens and its components, and say what you needed and could not find.";
     const head = [
@@ -408,6 +481,28 @@ async function listComponents(root) {
  * properties need to be dynamic - the more we map, the more precision". A list written
  * into a published package is a list that stops matching the contract.
  */
+/**
+ * O PLAYBOOK, na fatia pedida (R1, dono 16/08): sem `section`, a moldura + o
+ * sumário; com, UM capítulo. O corpo inteiro nunca viaja - a dieta de contexto
+ * é servida por construção.
+ */
+async function playbook(skill, section) {
+    const answer = await askCatalogue("playbook", undefined, section ? { skill, section } : { skill });
+    if (!answer.ok)
+        return answer.because;
+    const body = answer.body;
+    if ("error" in body)
+        return [body.error, body.hint].filter(Boolean).join("\n");
+    if ("sections" in body) {
+        return [
+            body.intro,
+            "",
+            "## Chapters - fetch ONLY the one for your current step",
+            ...body.sections.map((c) => `- ${c.id} - ${c.title}`),
+        ].join("\n");
+    }
+    return body.body;
+}
 async function recipeVocabulary() {
     const answer = await askCatalogue("vocabulary");
     if (!answer.ok)
@@ -769,7 +864,9 @@ cli) {
         }
     })();
 }
-async function askCatalogue(want, post) {
+async function askCatalogue(want, post, 
+/** Parâmetros extras do GET (ex.: o playbook e o capítulo pedidos). */
+query) {
     const token = await readToken();
     if (!token) {
         return {
@@ -779,7 +876,8 @@ async function askCatalogue(want, post) {
     }
     const base = resolveRegistry();
     try {
-        const res = await fetch(`${base}/api/catalogue${post ? "" : `?want=${want}`}`, post
+        const extra = query ? `&${new URLSearchParams(query).toString()}` : "";
+        const res = await fetch(`${base}/api/catalogue${post ? "" : `?want=${want}${extra}`}`, post
             ? {
                 method: "POST",
                 headers: {
@@ -966,6 +1064,11 @@ cli) {
         case "add_component":
             countAgentRead(root, String(args.name ?? ""), "add", cli);
             return text(await addComponent(root, String(args.name ?? "")));
+        case "playbook": {
+            const skill = String(args?.skill ?? "");
+            const section = args?.section ? String(args.section) : undefined;
+            return text(await playbook(skill, section));
+        }
         case "recipe_vocabulary":
             return text(await recipeVocabulary());
         case "validate_recipe": {

package/dist/commands/refit.js

@@ -123,12 +123,15 @@ export async function refit(file, opts) {
         recipe: res.recipe,
     });
     console.log(`✓ saved into "${slug}" (draft v${saved.version} - ships with your next publish)`);
-    // 5. materialize back into the project: artifacts + YOUR typed component
-    const artifactsDir = join(root, "_synthesisui", "ds", slug, "components");
-    await mkdir(artifactsDir, { recursive: true });
-    await writeFile(join(artifactsDir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
-    await writeFile(join(artifactsDir, `${res.name}.css`), `${res.css}\n`, "utf8");
+    // 5. materialize back into the project: YOUR typed component - e as cópias
+    // .json/.css só quando são o produto (target não-Next; R3, dono 16/08).
     const config = await readProjectConfig(root);
+    if (config.target !== "next") {
+        const artifactsDir = join(root, "_synthesisui", "ds", slug, "components");
+        await mkdir(artifactsDir, { recursive: true });
+        await writeFile(join(artifactsDir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
+        await writeFile(join(artifactsDir, `${res.name}.css`), `${res.css}\n`, "utf8");
+    }
     let materialized = false;
     if (config.target === "next") {
         const compDir = join(root, config.componentsDir, res.name);

package/dist/commands/sync.js

@@ -269,9 +269,9 @@ export async function remeasure(args) {
         }
     }
     console.log(section("Measuring your repository again"));
-    console.log(body(paint.faint(`${scope ? `scope ${scope}` : "the whole repo"}${local.system && local.system !== stored.scope
-        ? " · read from your own census, which is where the last measurement recorded it"
-        : ""} · the reading you already authored travels unchanged`)));
+    console.log(body(paint.faint(`${scope ? `reading ${scope}` : "the whole repo"}${local.system && local.system !== stored.scope
+        ? " · read from _synthesisui/census.json, where the last measurement recorded it"
+        : ""} · what you already wrote about your app travels unchanged`)));
     const census = await takeCensus(scope ? join(root, scope) : root, {
         ...(scope ? { scopeLabel: scope } : {}),
         ...(args.cli ? { cli: args.cli } : {}),
@@ -333,7 +333,7 @@ export async function remeasure(args) {
      * repositório inteiro e o rascunho curado de 37 vira 339).
      */
     if (!fresh.scope && local.system)
-        console.log(body(`⚠ the census was written without a scope while "${local.system}" is the one recorded - the next re-measure would read the whole repo. Please report this: it is a state we have not reproduced.`));
+        console.log(body(`⚠ the last measurement was saved without the folder it read, while "${local.system}" is the one recorded - the next one would read the whole repo. Please report this: it is a state we have not reproduced.`));
     if (usage.length > 0)
         fresh.usage = usage;
     for (const key of ["scheme", "reading"])

package/dist/commands/use.js

@@ -57,14 +57,43 @@ export async function use(slug, intent, opts) {
             : "",
         `- ${base}/v${version}/GUIDE.md - how to apply the system, the recipes and the token vocabulary`,
     ].filter(Boolean);
+    /**
+     * OS EXEMPLOS SÃO DO SISTEMA DELE, não uma lista nossa de cor. `bg-primary`/`p-md` cravados
+     * ensinavam classes que um sistema importado pode nem compilar - os nomes reais moram no
+     * `design-system.json` instalado, e é dele que os exemplos saem. Ilegível, ficam os genéricos.
+     */
+    let utilities = "`bg-primary`, `text-foreground`, `p-md`, `rounded-lg`, `font-display`";
+    try {
+        const doc = JSON.parse(await readFile(join(slugDir, `v${version}`, "design-system.json"), "utf8"));
+        const roles = Object.keys(doc.foundations?.color?.semantic ?? {});
+        const spacing = Object.keys(doc.foundations?.spacing ?? {});
+        const radius = Object.keys(doc.foundations?.radius ?? {});
+        const parts = [
+            roles.length > 0
+                ? `\`bg-${roles.includes("primary") ? "primary" : roles[0]}\``
+                : null,
+            roles.includes("foreground")
+                ? "`text-foreground`"
+                : roles[1]
+                    ? `\`text-${roles[1]}\``
+                    : null,
+            spacing[0] ? `\`p-${spacing[0]}\`` : null,
+            radius[0] ? `\`rounded-${radius[0]}\`` : null,
+            "`font-display`",
+        ].filter(Boolean);
+        if (parts.length >= 3)
+            utilities = parts.join(", ");
+    }
+    catch {
+        // sem manifesto legível, os exemplos genéricos ficam - pior seria nenhum
+    }
     // The styling contract differs by target: Next projects in this product use
     // Tailwind v4 backed by the DS; the "general" target is framework-agnostic CSS.
     const stylingRule = config.target === "general"
         ? `- Style with the design system only: reuse the \`.ds-*\` recipe classes and the ` +
             `\`var(--ds-*)\` custom properties. Never use raw hex/px outside the system's scale.`
         : `- Style with the design system only: reuse the \`.ds-*\` recipe classes and the ` +
-            `DS-backed Tailwind utilities (\`bg-primary\`, \`text-foreground\`, \`p-md\`, \`rounded-lg\`, ` +
-            `\`font-display\`…). Never use raw hex/px outside the system's scale.`;
+            `DS-backed Tailwind utilities (${utilities}…). Never use raw hex/px outside the system's scale.`;
     const task = intent.trim() || "build the UI I describe next";
     const prompt = [
         `Use the "${name}" design system (slug: ${slug}, v${version}) to: ${task}`,

package/dist/doctor/ci-format.js

@@ -79,12 +79,20 @@ export function compareToBaseline(d, base, now) {
             : {}),
     };
 }
-/** O que a mensagem de uma anotação diz, e é a mesma frase nos dois formatos. */
+/**
+ * O que a mensagem de uma anotação diz, e é a mesma frase nos dois formatos.
+ *
+ * O NOME DELE PRIMEIRO, como em todo o resto do doctor (`nameToWrite`): este era o único caminho
+ * que ignorava `their-names` por completo - e é o que aparece anotado na linha do PR de todo o
+ * time dele. Um `theirToken` também desarma o caso `crossFamily`: o repo DELE nomeia o valor, então
+ * a troca existe (mesma regra de `apply-fix.ts`).
+ */
 function messageFor(f) {
-    return f.token
-        ? f.crossFamily
+    const shown = f.theirToken ?? f.token;
+    return shown
+        ? f.crossFamily && !f.theirToken
             ? `${f.literal} is written by hand, and this project's system has no ${f.kind} named for it. The value does exist elsewhere in the system - as \`${f.token}\`, in another family - so this is a decision to make, not a swap: name a ${f.kind}, or leave it.`
-            : `${f.literal} is written by hand, and this project's system already names it: var(${f.token}). Use the token.`
+            : `${f.literal} is written by hand, and this project already names it: var(${shown}). Use the name.`
         : `${f.literal} is a ${f.kind} value written by hand, and the system has no name for it yet. Name it, or file a token request: npx synthesisui request token`;
 }
 /**
@@ -192,7 +200,8 @@ export function describeVerdict(v) {
         lines.push(`Baseline not comparable: ${v.incomparable}.`);
         return lines;
     }
-    lines.push(`Drift ${v.drift.was} → ${v.drift.now}${v.phantoms.was || v.phantoms.now ? ` · phantom tokens ${v.phantoms.was} → ${v.phantoms.now}` : ""}.`);
+    /** "Drift"/"phantom" são palavras nossas - a linha fala do que ELE vê: valores à mão e nomes que não resolvem. */
+    lines.push(`Hand-written values ${v.drift.was} → ${v.drift.now}${v.phantoms.was || v.phantoms.now ? ` · names that resolve to nothing ${v.phantoms.was} → ${v.phantoms.now}` : ""}.`);
     if (v.improved > 0)
         lines.push(`${v.improved} file${v.improved === 1 ? "" : "s"} improved since the baseline.`);
     if (v.regressed.length === 0) {

package/dist/doctor/tokens.js

@@ -467,7 +467,9 @@ export function buildTable(input) {
  * Deliberately narrow: same unit, within 25% or 8px, and never for a colour -
  * "nearly the same blue" is exactly the guess this tool must not make.
  */
-export function nearestToken(table, literal) {
+export function nearestToken(table, literal, 
+/** A família do achado - com ela, o vizinho também é oferecido pelo NOME DELE quando o repo o nomeia. */
+kind) {
     const m = /^(-?\d*\.?\d+)(px|rem)$/.exec(literal.trim().toLowerCase());
     if (!m)
         return null;
@@ -490,7 +492,17 @@ export function nearestToken(table, literal) {
     if (!best)
         return null;
     const limit = unit === "rem" ? Math.max(n * 0.25, 0.5) : Math.max(n * 0.25, 8);
-    return best.delta <= limit ? best : null;
+    if (best.delta > limit)
+        return null;
+    /**
+     * O VIZINHO PELO NOME DELE - a mesma chave que `theirNames` construiu (`kind:valor`), porque o
+     * valor sozinho não decide a família. Só a tabela nossa era consultada aqui, então a oferta saía
+     * sempre no nosso vocabulário mesmo quando o repo dele nomeia o mesmo valor.
+     */
+    const theirs = kind
+        ? table.aliases.get(`${kind}:${normalizeValue(best.value, table.rootPx)}`)
+        : undefined;
+    return theirs ? { ...best, theirs } : best;
 }
 /**
  * The family a token belongs to, from the drift it was found in.