synthesisui 0.16.487 → 0.16.488

package/dist/claude-md.js

@@ -455,6 +455,20 @@ and task, call it once - an empty result means there is nothing more to retrieve
 tells you what was decided and why it matters; **the file on disk is still the authority for what is
 written now** - read the code before you edit it, never a remembered signature.`
         : "";
+    /**
+     * OS BLUEPRINTS DELA, LIGADOS - era "só quando ela pede" (02/10); desde 03/10 ficam ligados e se desligam por projeto.
+     * Ele: "isso tem que ficar ativado sempre e desativado se a gente precisar". No teste final a base só chegou no
+     * pedido que dizia a frase - 1 de 5. Jornada "a conta nasce com a base". O texto abaixo é o de 02/10: O
+     * blueprint de preferências mora na conta da pessoa e serve todo projeto dela; a linha diz ao agente
+     * as duas portas e a regra que as mantém fechadas no dia a dia: quem cria sem pedir continua livre.
+     * Basta o servidor registrado - a preferência não depende do sistema instalado.
+     */
+    const preferencesLine = recall.available
+        ? `
+
+**Their page blueprints are on:** call \`preferences\` with the page's kind before building one, unless
+they say not to (\`synthesisui preferences off\`); a correction to keep is \`remember_preference\`.`
+        : "";
     /**
      * O TEMA É DELE - bateria ampliada, item 22 (29/09). Em c01, c02, c05, c17 e c23 o agente mexeu no tema do projeto
      * sem perguntar: `--text-xl` no globals.css para "casar com a escala", 17 valores no tailwind.config.js, três cores
@@ -470,7 +484,7 @@ new token invented in silence - say so instead, because a new token is a decisio
 is no component index for an adopted system: the tokens ARE the contract.${theirsLine}
 
 **What the vocabulary IS is not written here.** Fetch only the piece the task requires:
-\`system_doctrine\` for the rules and the voice, \`find_token\` for a value you are about to write.${memoryLine}${selfCheck}`
+\`system_doctrine\` for the rules and the voice, \`find_token\` for a value you are about to write.${memoryLine}${preferencesLine}${selfCheck}`
             : `**These are true without asking anyone:**
 
 - The system's vocabulary only - and it is written in the names THIS project declares. \`find_token\`
@@ -493,7 +507,7 @@ If nothing covers it, say which indexed entry you considered and why it did not
 
     describe_component   its parts, variants, states and the tokens it already uses
     system_doctrine      the rules and the voice of this system
-    playbook             the families, and what each one requires before it can be drawn${memoryLine}${selfCheck}`
+    playbook             the families, and what each one requires before it can be drawn${memoryLine}${preferencesLine}${selfCheck}`
         : onlyAdopted
             ? `**When creating or editing components, read the system's GUIDE.md and follow it:** use the
 project's OWN custom properties, exactly as the guide lists them. Do not write raw colours,

package/dist/commands/add.js

@@ -4,6 +4,7 @@ import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { parseRules } from "../doctrine.js";
+import { wireTheme } from "../first-theme.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
 import { detectAppDirs } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
@@ -737,6 +738,15 @@ export async function add(slug, opts) {
                 : `  CLAUDE.md already current - nothing to rewrite (${claudeMd.count} system(s) indexed)`);
     if (opts.setupHints === false)
         return;
+    /**
+     * O TEMA LIGADO NA INSTALAÇÃO (03/10) - o `add` chamado direto liga o tema de um projeto que ainda não tem o seu, como
+     * o `init --ds` já fazia. Ver `first-theme.ts`. O `init` chama o `add` com `setupHints: false` e cuida do tema ele mesmo.
+     */
+    const wired = await wireTheme(projectRoot, slug);
+    if (wired.written) {
+        console.log("");
+        console.log(`✓ ${wired.written}: ${wired.count} names of ${slug} declared in your own ${wired.where}, with the values written - your project had none of its own, so installing the system turns its theme on.`);
+    }
     // ── DX: concrete paths + copy-pasteable snippets, with breathing room ──
     // Where the app actually lives (app/ vs src/app/) still drives where `fonts.ts`
     // lands and which layout the snippet names. The @import depth went with the
@@ -879,7 +889,10 @@ export async function add(slug, opts) {
         const named = [
             ...new Set(Object.values(families)
                 .filter((f) => typeof f === "string")
-                .map((f) => f.split(",")[0]?.trim().replace(/^["']|["']$/g, "") ?? "")
+                .map((f) => f
+                .split(",")[0]
+                ?.trim()
+                .replace(/^["']|["']$/g, "") ?? "")
                 .filter(Boolean)),
         ];
         if (opts.fromImport) {

package/dist/commands/mcp.js

@@ -1,5 +1,4 @@
 import { readFileSync } from "node:fs";
-import { ourSpellingLines } from "../our-spelling.js";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { provenanceAction, toolSlug, withSource, } from "../agent-provenance.js";
@@ -11,11 +10,13 @@ import { declareForm } from "../doctor/declared-forms.js";
 import { describeTriage, triageLedger } from "../doctor/gap-triage.js";
 import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
-import { describeOffScale, diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
+import { describeOffScale, diagnose, nameToWrite, scanSource, } from "../doctor/scan.js";
 import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
 import { ruleLine } from "../doctrine.js";
 import { fromCensus } from "../memory/observation.js";
 import { handleRecall, handleRemember, MEMORY_TOOLS } from "../memory/tools.js";
+import { ourSpellingLines } from "../our-spelling.js";
+import { fetchPreferences, isKind, isLayer, PREFERENCE_KINDS, PREFERENCE_LAYERS, preferencesAnswer, readOff, readSelection, sendPiece, } from "../preferences.js";
 import { readInstalledConvention } from "../project-facts.js";
 import { repoStateOf } from "../repo-state.js";
 import { detectStack } from "../stack.js";
@@ -361,6 +362,47 @@ const TOOLS = [
      * derivado aparece neles - `memory/tools.spec.ts` percorre os dois e reprova se um vazar.
      */
     ...MEMORY_TOOLS,
+    /**
+     * O BLUEPRINT DE PREFERÊNCIAS - o jeito da PESSOA montar um tipo de página, guardado na conta
+     * dela (jornada "o blueprint de template", 02/10). Duas ferramentas, e as duas só se chamam
+     * quando ELA pede: quem cria sem pedir continua livre ("ela não deve travar o usuário lá na hora
+     * que ele estiver na parte criativa dele").
+     */
+    {
+        name: "preferences",
+        description: "The person's OWN preference blueprint for a kind of page - how they like a landing, a blog article or a dashboard built (structure, behavior, view), kept in their account and shared by all their projects. Call this BEFORE building or reshaping a page of one of these kinds - their blueprints are on by default, so a plain \"make me a landing page\" gets them too. Skip it only when the request says to build without them; a project that turned them off answers so itself. The rules name roles and steps; you resolve them to this project's --ds-* variables.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: [...PREFERENCE_KINDS],
+                    description: "Which kind of page is being built.",
+                },
+            },
+            required: ["kind"],
+        },
+    },
+    {
+        name: "remember_preference",
+        description: 'Keep ONE preference the person just told you about how a kind of page should be built - a correction they made ("the hero needs more room", "I like the menu sliding from the right") or something they asked you to remember. Call it only when THEY say it, never from your own taste. It lands loose in their account; nothing joins a blueprint until they group it on the site. Write it with roles and steps, never values: "the accent role", "the largest spacing step" - a hex or a pixel size is refused, because it would tie the preference to one system.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: { type: "string", enum: [...PREFERENCE_KINDS] },
+                layer: {
+                    type: "string",
+                    enum: [...PREFERENCE_LAYERS],
+                    description: "structure = sections, room, drawing, what never misses · behavior = motion, transitions, the phone menu · view = focus, parallax, smooth or raw",
+                },
+                text: {
+                    type: "string",
+                    description: "The preference in one sentence, as the person would say it.",
+                },
+            },
+            required: ["kind", "layer", "text"],
+        },
+    },
 ];
 /**
  * QUANTAS FERRAMENTAS ESTE SERVIDOR SERVE, lido da lista.
@@ -1890,6 +1932,31 @@ cli) {
                 });
             });
         }
+        case "preferences": {
+            const kind = args.kind;
+            if (!isKind(kind))
+                return fromContract(`kind is one of ${PREFERENCE_KINDS.join(", ")} - say which kind of page is being built.`);
+            const token = await readToken();
+            if (!token)
+                return fromContract("Not signed in, so the person's preferences cannot be read. They have to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.");
+            const prefs = await fetchPreferences({ base: resolveRegistry(), token }, kind);
+            if ("failed" in prefs)
+                return fromContract(`Their preferences could not be read: ${prefs.failed}. Build with the system as usual and say so in one line.`);
+            return preferencesAnswer(kind, prefs, await readSelection(root), await readOff(root));
+        }
+        case "remember_preference": {
+            const { kind, layer } = args;
+            const text = String(args.text ?? "").trim();
+            if (!isKind(kind) || !isLayer(layer) || !text)
+                return fromContract(`Not kept: send kind (${PREFERENCE_KINDS.join(", ")}), layer (${PREFERENCE_LAYERS.join(", ")}) and the text.`);
+            const token = await readToken();
+            if (!token)
+                return fromContract("Not signed in, so nothing can be kept. They have to run `synthesisui login` once in the terminal.");
+            const out = await sendPiece({ base: resolveRegistry(), token }, { kind, layer, text });
+            return out.ok
+                ? fromContract(`Kept, loose, in their ${kind} preferences: "${text}". Tell them in one line that they can group it into a blueprint under Memory -> Preference blueprints on the site.`)
+                : fromContract(`Not kept: ${out.message}`);
+        }
         case "recall": {
             const reach = await memoryReach(root);
             if (typeof reach === "string")

package/dist/commands/preferences.js

@@ -0,0 +1,75 @@
+import { readToken, resolveRegistry } from "../config.js";
+import { chosen, describeBlueprint, fetchPreferences, readSelection, selectionPath, writeOff, writeSelection, } from "../preferences.js";
+/**
+ * `synthesisui preferences` - os blueprints de preferências da pessoa, e quais ESTE projeto usa.
+ *
+ *     preferences                  lista os dela, marcando os que este projeto usa
+ *     preferences use <nome>...    este projeto passa a usar só esses (nome ou id)
+ *     preferences use --all        volta a usar todos os dela (apaga o arquivo do projeto)
+ *     preferences off | on         desliga ou liga os blueprints neste projeto (ligados por padrão desde 03/10)
+ *
+ * O blueprint mora na conta dela; o projeto só guarda o recorte, em `_synthesisui/preferences.json`,
+ * versionado - escolher quais preferências um projeto segue é decisão do projeto, e viaja com ele.
+ */
+export async function preferences(opts) {
+    const root = opts.dir ?? process.cwd();
+    const token = await readToken();
+    if (!token) {
+        console.error("Not signed in - run `synthesisui login` first. Your preference blueprints live in your account.");
+        process.exitCode = 1;
+        return;
+    }
+    const prefs = await fetchPreferences({
+        base: resolveRegistry(opts.registry),
+        token,
+    });
+    if ("failed" in prefs) {
+        console.error(`Your preferences could not be read: ${prefs.failed}.`);
+        process.exitCode = 1;
+        return;
+    }
+    const [sub, ...names] = opts.args;
+    if (sub === "off" || sub === "on") {
+        await writeOff(root, sub === "off");
+        console.log(sub === "off"
+            ? "Your blueprints are off for this project - the agent builds with the system as usual. `synthesisui preferences on` turns them back on."
+            : "Your blueprints are on for this project - the agent reads them before building a page.");
+        return;
+    }
+    if (sub === "use") {
+        if (opts.all) {
+            await writeSelection(root, null);
+            console.log(`This project now uses all ${prefs.blueprints.length} of your preference blueprints.`);
+            return;
+        }
+        if (names.length === 0) {
+            console.error("Say which: `synthesisui preferences use <name>...`, or `--all` for every one of yours.");
+            process.exitCode = 1;
+            return;
+        }
+        const found = chosen(prefs.blueprints, names);
+        const missing = names.filter((n) => !found.some((b) => b.name.toLowerCase() === n.toLowerCase() || b.id === n));
+        if (missing.length > 0) {
+            console.error(`Not yours: ${missing.map((m) => `"${m}"`).join(", ")}. Yours are: ${prefs.blueprints.map((b) => `"${b.name}"`).join(", ") || "none yet"}.`);
+            process.exitCode = 1;
+            return;
+        }
+        await writeSelection(root, found.map((b) => b.name));
+        console.log(`This project now uses ${found.map((b) => `"${b.name}" (${b.kind})`).join(", ")} - written to ${selectionPath(root)}.`);
+        return;
+    }
+    const selection = await readSelection(root);
+    const using = new Set(chosen(prefs.blueprints, selection).map((b) => b.id));
+    if (prefs.blueprints.length === 0) {
+        console.log("No preference blueprints yet. Keep them on the site, under Memory -> Preference blueprints - or ask your agent to remember a correction you make.");
+    }
+    else {
+        console.log(selection === null
+            ? "Your preference blueprints - this project uses all of them:"
+            : "Your preference blueprints - [x] is what this project uses:");
+        for (const b of prefs.blueprints)
+            console.log(`\n[${using.has(b.id) ? "x" : " "}] ${describeBlueprint(b)}`);
+    }
+    if (prefs.loose.length > 0)
+        console.log(`\n${prefs.loose.length} loose piece(s) waiting to be grouped on the site.`);
+}

package/dist/first-theme.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readProjectTheme, writeNewProjectRoot, writeNewProjectTheme, } from "./new-project-theme.js";
+import { resolveDeps, tailwindMajor } from "./stack.js";
+/**
+ * O TEMA LIGADO NA INSTALAÇÃO - a jornada "a conta nasce com a base" (03/10).
+ *
+ * No teste final o pedido simples parou antes de montar a página: "As regras do projeto me proíbem de mexer no tema sem
+ * você pedir". O `init --ds` já ligava o tema de um projeto novo; o `add`, que o site também manda rodar, não. Ele,
+ * 16:39: "liga o tema sozinho na primeira página" - instalar o sistema já é o sim.
+ *
+ * A trava é a mesma do `init`: SÓ o projeto sem vocabulário próprio. Projeto que já nomeia os tokens dele não recebe
+ * nada - "os outros, eles têm que se comportar de acordo com o padrão do próprio projeto do usuário" (27/09).
+ *
+ *     Tailwind v4   os nomes do sistema no @theme dele, com os valores (writeNewProjectTheme)
+ *     sem Tailwind  os nomes no :root dele (writeNewProjectRoot), que já recusa um projeto com nomes próprios
+ */
+export async function wireTheme(root, ds) {
+    const slugDir = join(root, "_synthesisui", "ds", ds);
+    const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
+    const version = typeof lock.version === "number" ? lock.version : null;
+    if (version === null)
+        return { written: null, count: 0, where: null };
+    const tokens = await readFile(join(slugDir, `v${version}`, "tokens.css"), "utf8").catch(() => "");
+    if (!tokens)
+        return { written: null, count: 0, where: null };
+    const deps = await resolveDeps(root).catch(() => ({}));
+    if (deps.tailwindcss) {
+        const major = tailwindMajor(deps);
+        if (major === null || major < 4)
+            return { written: null, count: 0, where: null };
+        const plan = await readProjectTheme(root, tokens, ds);
+        if (plan?.kind !== "new")
+            return { written: null, count: 0, where: null };
+        const t = await writeNewProjectTheme(root, tokens, ds, version);
+        return {
+            written: t.written,
+            count: t.count,
+            where: t.written ? "@theme" : null,
+        };
+    }
+    const t = await writeNewProjectRoot(root, tokens, ds, version);
+    return {
+        written: t.written,
+        count: t.count,
+        where: t.written ? ":root" : null,
+    };
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { align } from "./commands/align.js";
 import { autopilot } from "./commands/autopilot.js";
 import { ci } from "./commands/ci.js";
 import { clean } from "./commands/clean.js";
+import { colours } from "./commands/colours.js";
 import { component } from "./commands/component.js";
 import { connect } from "./commands/connect.js";
 import { doctor } from "./commands/doctor.js";
@@ -24,6 +25,7 @@ import { login } from "./commands/login.js";
 import { logout } from "./commands/logout.js";
 import { mcp } from "./commands/mcp.js";
 import { mode } from "./commands/mode.js";
+import { preferences } from "./commands/preferences.js";
 import { refit } from "./commands/refit.js";
 import { request } from "./commands/request.js";
 import { status } from "./commands/status.js";
@@ -31,7 +33,6 @@ import { summary } from "./commands/summary.js";
 import { sync } from "./commands/sync.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
-import { colours } from "./commands/colours.js";
 import { use } from "./commands/use.js";
 import { appendEvent } from "./doctor/ledger.js";
 import { blueprintTarget, installedSlugs } from "./installed.js";
@@ -87,6 +88,10 @@ Usage - governance (deterministic, FREE):
                                            the measurement, --yes skips the overwrite question)
   synthesisui doctor --fix [--write]        show every hand-written value your system already names,
                                            and the token for it. --write applies them in place
+  synthesisui preferences                  your preference blueprints (how YOU build a landing, a blog,
+                                           a dashboard) and which ones this project uses
+  synthesisui preferences use <name>...    this project follows only those (--all: every one of yours)
+  synthesisui preferences off | on         turn your blueprints off or on for this project (on by default)
   synthesisui status                       where this project stands: installed version, last check,
                                            the ratchet, open requests - local first, no login needed
   synthesisui ci [--write]                 the two steps that put drift in your PR - annotations on
@@ -438,6 +443,10 @@ async function main() {
             });
             break;
         }
+        case "preferences":
+            /** Os blueprints de preferências dela - ver `commands/preferences.ts`. */
+            await preferences({ dir, registry, args, all: flags.all === true });
+            break;
         case "status":
             /** A resposta do dia a dia no terminal - ver `commands/status.ts`. Local primeiro. */
             await status({ dir, registry, cli: CLI_VERSION });
@@ -542,7 +551,9 @@ async function main() {
                 componentsDir,
                 styles,
                 ds,
-                ...(typeof flags["theme-in"] === "string" ? { themeIn: flags["theme-in"] } : {}),
+                ...(typeof flags["theme-in"] === "string"
+                    ? { themeIn: flags["theme-in"] }
+                    : {}),
                 cli: CLI_VERSION,
             });
             break;

package/dist/install-marks.js

@@ -314,7 +314,12 @@
  * 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";
+/**
+ * 0.16.483 -> 0.16.488 em 02/10, e o passo 1 dá **SIM** (o blueprint de template, E05): o bloco do `CLAUDE.md` ganha a
+ * linha das preferências da pessoa - `preferences` quando ela pede, `remember_preference` quando ela corrige. Uma pasta
+ * escrita antes não diz ao agente que essas portas existem.
+ */
+export const MATERIALISER_SINCE = "0.16.488";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/preferences.js

@@ -0,0 +1,200 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * O BLUEPRINT DE PREFERÊNCIAS, DO LADO DO AGENTE - o jeito da PESSOA montar uma landing, um blog ou
+ * um dashboard, guardado na conta dela e não no sistema.
+ *
+ * Três regras, e todas vêm do pedido dele (02/10):
+ *
+ *     SÓ QUANDO ELA PEDE   "ela não deve travar o usuário lá na hora que ele estiver na parte
+ *                          criativa dele" - o agente lê o blueprint quando o pedido diz para usar as
+ *                          preferências, nunca em todo turno
+ *     PAPÉIS, NÃO VALORES  o blueprint fala de "o destaque" e "o maior passo de espaço"; quem vira cor
+ *                          é o sistema DESTE projeto, pelas --ds-*
+ *     O PROJETO ESCOLHE    `_synthesisui/preferences.json` diz quais blueprints dela este projeto usa.
+ *                          Sem o arquivo, valem todos os dela daquele tipo
+ */
+export const PREFERENCE_KINDS = ["landing", "blog", "dashboard"];
+export const PREFERENCE_LAYERS = ["structure", "behavior", "view"];
+export const isKind = (k) => typeof k === "string" && PREFERENCE_KINDS.includes(k);
+export const isLayer = (l) => typeof l === "string" && PREFERENCE_LAYERS.includes(l);
+/** Onde o projeto guarda quais blueprints dela ele usa - versionado, porque é decisão do projeto. */
+export const selectionPath = (root) => join(root, "_synthesisui", "preferences.json");
+export async function readSelection(root) {
+    const raw = await readFile(selectionPath(root), "utf8").catch(() => null);
+    if (raw === null)
+        return null;
+    try {
+        const j = JSON.parse(raw);
+        return Array.isArray(j.use) ? j.use.map(String) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * DESLIGAR NO PROJETO (03/10) - os blueprints ficam ligados por padrão, "e desativado se a gente precisar". O mesmo
+ * arquivo do recorte guarda `off: true`; ligar de novo tira a chave e mantém o recorte.
+ */
+export async function readOff(root) {
+    const raw = await readFile(selectionPath(root), "utf8").catch(() => null);
+    if (raw === null)
+        return false;
+    try {
+        return JSON.parse(raw).off === true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function writeOff(root, off) {
+    const raw = await readFile(selectionPath(root), "utf8").catch(() => null);
+    let j = {};
+    try {
+        j = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        j = {};
+    }
+    if (off)
+        j.off = true;
+    else
+        delete j.off;
+    if (Object.keys(j).length === 0) {
+        await rm(selectionPath(root), { force: true });
+        return;
+    }
+    await mkdir(join(root, "_synthesisui"), { recursive: true });
+    await writeFile(selectionPath(root), `${JSON.stringify(j, null, 2)}\n`);
+}
+export async function writeSelection(root, names) {
+    if (names === null) {
+        await rm(selectionPath(root), { force: true });
+        return;
+    }
+    await mkdir(join(root, "_synthesisui"), { recursive: true });
+    const off = await readOff(root);
+    await writeFile(selectionPath(root), `${JSON.stringify(off ? { use: names, off } : { use: names }, null, 2)}\n`);
+}
+/** Os blueprints que este projeto usa: o recorte do arquivo, ou todos os dela. Nome ou id servem. */
+export function chosen(all, selection) {
+    if (selection === null)
+        return all;
+    const want = new Set(selection.map((s) => s.toLowerCase()));
+    return all.filter((b) => want.has(b.name.toLowerCase()) || want.has(b.id.toLowerCase()));
+}
+export async function fetchPreferences(reach, kind) {
+    const res = await fetch(`${reach.base}/api/preferences${kind ? `?kind=${kind}` : ""}`, { headers: { Authorization: `Bearer ${reach.token}` } }).catch(() => null);
+    if (!res)
+        return { failed: "the platform could not be reached" };
+    if (!res.ok)
+        return { failed: `the platform answered ${res.status}` };
+    const j = (await res.json().catch(() => null));
+    return j ?? { failed: "the platform answered something unreadable" };
+}
+export async function sendPiece(reach, piece) {
+    const res = await fetch(`${reach.base}/api/preferences/pieces`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            Authorization: `Bearer ${reach.token}`,
+        },
+        body: JSON.stringify({ ...piece, origin: "correction" }),
+    }).catch(() => null);
+    if (!res)
+        return { ok: false, message: "the platform could not be reached" };
+    const j = (await res.json().catch(() => null));
+    if (!res.ok)
+        return {
+            ok: false,
+            message: j?.message ?? `the platform answered ${res.status}`,
+        };
+    return { ok: true, id: String(j?.id ?? "") };
+}
+const LAYER_TITLE = {
+    structure: "STRUCTURE",
+    behavior: "BEHAVIOR",
+    view: "VIEW",
+};
+/** As escolhas de guia em palavras - o agente não tem guia, então elas viram instrução. */
+function choicesLines(c) {
+    const out = [];
+    if (c.density)
+        out.push(`section rhythm: ${c.density}`);
+    if (c.transitions)
+        out.push(`between sections: ${c.transitions}`);
+    if (c.icons === "custom")
+        out.push("icons: their own inline SVG drawings, painted with the system's colour roles");
+    const nav = (c.navbar ?? {});
+    if (nav.mobile)
+        out.push(`phone menu: ${nav.mobile}`);
+    if (nav.sticky !== undefined)
+        out.push(nav.sticky
+            ? "navigation sticks on scroll"
+            : "navigation stays solid in the flow");
+    if (c.heroMotion)
+        out.push(`hero motion: ${c.heroMotion}`);
+    if (c.sectionMotion)
+        out.push(`section motion: ${c.sectionMotion}`);
+    return out;
+}
+export function describeBlueprint(b) {
+    const groups = PREFERENCE_LAYERS.map((l) => ({
+        l,
+        rules: b.pieces.filter((p) => p.layer === l),
+    })).filter((g) => g.rules.length > 0);
+    const choices = choicesLines(b.guideChoices);
+    return [
+        `"${b.name}" (${b.kind})`,
+        ...groups.flatMap((g) => [
+            `  ${LAYER_TITLE[g.l]}:`,
+            ...g.rules.map((r) => `  - ${r.text}`),
+        ]),
+        ...(choices.length > 0
+            ? ["  THEIR USUAL CHOICES:", ...choices.map((c) => `  - ${c}`)]
+            : []),
+    ].join("\n");
+}
+/** A linha de procedência é o servidor quem escreve, a partir de `source` - aqui ela sairia duas vezes. */
+const composed = (body, detail) => ({
+    body,
+    source: { kind: "composed", detail },
+});
+/** O que a plataforma sabe de montar ESTE tipo - vem depois dos blueprints dela, que ganham dele quando discordam. */
+function craftOf(kind, prefs) {
+    const lines = prefs.craft?.[kind] ?? [];
+    if (lines.length === 0)
+        return [];
+    return [
+        "",
+        `HOW THIS PLATFORM BUILDS A ${kind.toUpperCase()} - the same rules its guide uses; their blueprint wins where the two disagree:`,
+        ...lines.map((l) => `- ${l}`),
+    ];
+}
+/** A resposta da ferramenta `preferences` - lida SÓ quando o pedido diz para usar as preferências dela. */
+export function preferencesAnswer(kind, prefs, selection, 
+/** O projeto desligou os blueprints (`synthesisui preferences off`). */
+off = false) {
+    if (off)
+        return composed(`This project turned the person's blueprints off (_synthesisui/preferences.json). Build the ${kind} with the system as usual; they turn them back on with \`synthesisui preferences on\`.`, `preferences:${kind}:off`);
+    const mine = prefs.blueprints.filter((b) => b.kind === kind);
+    const use = chosen(mine, selection);
+    if (use.length === 0) {
+        const why = mine.length === 0
+            ? `The person has no ${kind} preference blueprint yet.`
+            : `The person has ${mine.length} ${kind} blueprint(s) (${mine.map((b) => `"${b.name}"`).join(", ")}), but this project chose others in _synthesisui/preferences.json.`;
+        // não ter preferência não é lacuna do sistema: é uma resposta verdadeira, e não entra na conta de lacunas
+        return composed(`${why} Build the ${kind} with the system as usual, and tell them in one line that they can keep their ${kind} preferences under Memory -> Preference blueprints on the site.`, `preferences:${kind}:0`);
+    }
+    return composed([
+        `The person's preference blueprint${use.length > 1 ? "s" : ""} for a ${kind} - THEIR preferences, kept by them across projects:`,
+        "",
+        ...use.map(describeBlueprint),
+        "",
+        "How to apply them:",
+        "- They name ROLES and STEPS, never values. Resolve every role to THIS project's --ds-* variables (the accent role is --ds-color-semantic-accent here, the largest spacing step is the system's largest --ds-spacing-*). Drawing is welcome: an inline SVG painted with fill/stroke on var(--ds-color-...) is the system's vocabulary, not drift.",
+        "- They win over generic page craft when the two disagree; this system's tokens and rules still win over them.",
+        `- When you finish, tell them in ONE line which blueprint you applied${use.length > 1 ? " (if more than one fits, use the first and name it)" : ""}, and any rule you could not follow and why.`,
+        ...craftOf(kind, prefs),
+    ].join("\n"), `preferences:${kind}:${use.length}`);
+}

package/package.json

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