synthesisui 0.16.243 → 0.16.247

package/dist/agent-provenance.js

@@ -0,0 +1,92 @@
+/**
+ * DE ONDE VEIO A RESPOSTA - e é um DADO, não uma frase (dono, 18/08).
+ *
+ * O pedido veio com a razão embutida: *"eu trataria a linha Source como algo
+ * estrutural mesmo, não só visual. Isso pode virar uma métrica de maturidade
+ * depois - porcentagem de respostas por receita, por composição, por
+ * improviso."*
+ *
+ * Então a procedência nasce como estrutura e o texto é DERIVADO dela. O
+ * contrário - escrever a frase à mão em cada resposta - produz duas verdades no
+ * dia em que uma delas for editada, e a que vai para a métrica é sempre a que
+ * ninguém leu.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE CADA KIND SIGNIFICA, e a fronteira é a GARANTIA
+ *
+ *   contract   veio do que este sistema declara - receita, token, regra,
+ *              vocabulário. A plataforma responde por isso.
+ *   composed   montado a partir de camadas porque não havia receita para o
+ *              pedido. Vale, e vale menos que um contrato. (Nasce com o
+ *              compose_context; hoje nada devolve isto, e é de propósito -
+ *              um kind que ninguém emite é um número que mente por otimismo.)
+ *   pointer    um ponteiro para conhecimento de terceiro. Não é nosso, não é
+ *              garantido, e a resposta diz o pacote. Mesma gramática que a
+ *              plataforma já usa: "3rd-party · <pacote>".
+ *   none       este sistema não tinha nada para o pedido. É o kind mais
+ *              valioso dos quatro: é ele que mede o improviso, e é o evento
+ *              que a plataforma não contava.
+ *
+ * A TAXA DE IMPROVISO é `none` sobre o total, e ela é a pergunta que decide se
+ * a composição vale ser construída - respondida com dado em vez de sensação.
+ */
+/**
+ * A LINHA QUE O AGENTE E A PESSOA LEEM - derivada, nunca escrita à mão.
+ *
+ * Ela serve dois leitores de uma vez: o dev sabe o quanto confiar no que
+ * acabou de receber, e o agente sabe se está pisando em contrato ou em
+ * composição. Um agente que não sabe a diferença trata as duas com a mesma
+ * confiança, e é assim que uma suposição nossa entra no repositório dele com
+ * cara de regra.
+ */
+export function sourceLine(source) {
+    const label = source.kind === "pointer"
+        ? "3rd-party pointer"
+        : source.kind === "none"
+            ? "none"
+            : source.kind;
+    return source.detail
+        ? `Source: ${label} · ${source.detail}`
+        : `Source: ${label}`;
+}
+/**
+ * O texto com a procedência colada no fim - uma linha em branco antes, para
+ * ela não se misturar com a última frase da resposta.
+ */
+export function withSource(answer) {
+    return `${answer.body}\n\n${sourceLine(answer.source)}`;
+}
+/**
+ * O VALOR GRAVADO, e o prefixo existe para o eixo ser legível numa tabela que
+ * já carrega outra coisa.
+ *
+ * `agent_reads.action` é `text` sem CHECK no banco (medido em produção), então
+ * um valor novo não custa migração - e uma coluna nova custaria a tabela
+ * inteira até a migração rodar. `src-` marca de qual eixo a linha fala:
+ * `describe`/`add` são gesto, `tool` é chamada, `src-*` é procedência.
+ *
+ * E UMA LACUNA LEVA O MOTIVO NO PRÓPRIO VALOR: `src-none-recipe`. Assim a
+ * pergunta agregada continua sendo um `like 'src-none%'` e a pergunta por
+ * motivo é a mesma consulta com o valor inteiro - sem coluna nova, e sem
+ * perder o total.
+ *
+ * Recebe a procedência INTEIRA e não o `kind`: com o kind sozinho, o motivo
+ * seria um segundo argumento que alguém esquece, e a linha gravada voltaria a
+ * ser um `none` cego.
+ */
+export function provenanceAction(source) {
+    return source.kind === "none"
+        ? `src-none-${source.reason}`
+        : `src-${source.kind}`;
+}
+/**
+ * O NOME DA FERRAMENTA COMO A TABELA O GUARDA.
+ *
+ * A coluna `component` aceita `^[a-z][a-z0-9-]*$` na rota - a mesma forma de um
+ * slug de receita. As ferramentas são snake_case, então elas viajam em
+ * kebab-case; sem isto o ping seria recusado com 400 e a instrumentação
+ * silenciaria justamente na ferramenta nova.
+ */
+export function toolSlug(tool) {
+    return tool.replace(/_/g, "-").toLowerCase();
+}

package/dist/commands/mcp.js

@@ -1,7 +1,9 @@
 import { readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { provenanceAction, toolSlug, withSource, } from "../agent-provenance.js";
 import { pinnedHookVersion } from "../agent-wiring.js";
+import { composePlan, FAMILIES, isFamily, noFamilyAnswer, renderPlan, } from "../compose-context.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
@@ -14,6 +16,16 @@ import { installedSlug, remeasure } from "./sync.js";
 const send = (msg) => {
     process.stdout.write(`${JSON.stringify(msg)}\n`);
 };
+/**
+ * A RESPOSTA QUE VEIO DO CONTRATO - o atalho, porque é o caso comum.
+ *
+ * `detail` fica de fora quando a própria resposta já nomeia a fonte (o token,
+ * o componente, a versão): repetir aquilo na linha de procedência é ruído.
+ */
+const fromContract = (body, detail) => ({
+    body,
+    source: { kind: "contract", ...(detail ? { detail } : null) },
+});
 /** A tool result is always text: readable by the model, and by a person
  *  watching the transcript when something goes wrong. */
 const text = (body, isError = false) => ({
@@ -111,14 +123,14 @@ const TOOLS = [
     },
     {
         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.",
+        description: "The skill playbooks (init, import, adapt, compose) - 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. `compose` is the hierarchy to walk when this system has no recipe for what you were asked to build - the layers it DOES have, in order.",
         inputSchema: {
             type: "object",
             properties: {
                 skill: {
                     type: "string",
-                    enum: ["init", "import", "adapt"],
-                    description: "Which playbook.",
+                    enum: ["init", "import", "adapt", "compose"],
+                    description: "Which playbook. `compose` is the one for building something this system has no recipe for.",
                 },
                 section: {
                     type: "string",
@@ -173,6 +185,24 @@ const TOOLS = [
             required: ["recipes"],
         },
     },
+    {
+        name: "compose_context",
+        description: "The layers to build something this system has NO recipe for, in one call: the recipes of that family to copy from, the tokens they already use with their values, the system's rules, and the floor and checklist for the family. YOU say which family it is - you just read the request, and a keyword guess of ours would be worse. Call this instead of asking for doctrine, vocabulary and each token separately; the laws of markup and the voice are named in the answer with the one fetch each needs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                family: {
+                    type: "string",
+                    description: `Which family this behaves like: ${FAMILIES.join(", ")}. Pick by BEHAVIOUR, never by the name in the request. If a part fits none of them, send what you would call it and the answer says what to do.`,
+                },
+                intent: {
+                    type: "string",
+                    description: "What you are building, in a few words - it is echoed back so your summary can name it.",
+                },
+            },
+            required: ["family"],
+        },
+    },
     {
         name: "request_component",
         description: "File a component request when nothing in the catalogue covers what you need. This is the OTHER HALF of the refusal rule: you already say which entry you considered and why it did not fit - said in chat, that reasoning evaporates; filed here, it becomes the queue the system's author works from. File it at the moment you build the workaround, while the reasoning is still yours.",
@@ -254,7 +284,10 @@ export const MCP_TOOL_COUNT = TOOLS.length;
 async function checkFile(root, path) {
     const { table } = await loadSystem(root);
     if (table.byName.size === 0)
-        return "No design system installed here, so there is nothing to check against. Run `synthesisui init` or `synthesisui adopt`.";
+        return {
+            body: "No design system installed here, so there is nothing to check against. Run `synthesisui init` or `synthesisui adopt`.",
+            source: { kind: "none", reason: "system", detail: "no system installed" },
+        };
     const scope = resolve(root, path);
     const reports = [];
     for await (const file of walkAll([scope])) {
@@ -263,7 +296,7 @@ async function checkFile(root, path) {
             reports.push(scanSource(relative(root, file), src, table));
     }
     if (reports.length === 0)
-        return `Nothing readable at ${path}.`;
+        return fromContract(`Nothing readable at ${path}.`);
     const d = diagnose(reports);
     const out = [
         `${table.name ?? table.slug}: ${d.coverage}% of design values come from the system.`,
@@ -284,12 +317,16 @@ async function checkFile(root, path) {
     }
     if (d.findings.length === 0 && phantoms.length === 0)
         out.push("", "Nothing to fix here.");
-    return out.join("\n");
+    return fromContract(out.join("\n"));
 }
 async function findToken(root, value) {
     const { table } = await loadSystem(root);
-    if (table.byName.size === 0)
-        return "No design system installed here.";
+    if (table.byName.size === 0) {
+        return {
+            body: "No design system installed here.",
+            source: { kind: "none", reason: "system", detail: "no system installed" },
+        };
+    }
     /**
      * 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`
@@ -306,16 +343,27 @@ async function findToken(root, value) {
     const exact = tokenFor(table, value);
     if (exact) {
         const shown = theirNameFor(value) ?? exact;
-        return `${value} is ${shown} in this project. Use var(${shown}).`;
+        return fromContract(`${value} is ${shown} in this project. Use var(${shown}).`);
     }
     const near = nearestToken(table, value);
     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.`;
+        /** Perto não é o valor: o sistema NÃO tem este, e a métrica precisa saber. */
+        return {
+            body: `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.`,
+            source: {
+                kind: "none",
+                reason: "token",
+                detail: `no token for ${value}`,
+            },
+        };
     }
     // 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.`;
+    return {
+        body: `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.`,
+        source: { kind: "none", reason: "token", detail: `no token for ${value}` },
+    };
 }
 /**
  * A DOUTRINA DO SISTEMA - as regras e a filosofia, servidas em vez de materializadas.
@@ -801,18 +849,28 @@ async function validateRecipes(root, entries) {
  * had 26 names against a catalogue of 41.
  */
 /**
- * O CONTADOR DO AGENTE, fire-and-forget: a tela do UI Kit mostra "vezes que esta receita
- * foi consultada pelo Agente", e este é o único ponto onde a consulta acontece de
- * verdade. Nunca bloqueia a resposta: sem sessão ou sem rede, não conta e não quebra -
- * telemetria que atrasa a ferramenta é telemetria que alguém desliga.
+ * O CONTADOR DO AGENTE, fire-and-forget e agora CENTRAL.
+ *
+ * Ele nasceu para uma tela: o UI Kit mostra "vezes que esta receita foi consultada pelo
+ * Agente". E era chamado à mão em duas ferramentas de treze, o que quer dizer que onze
+ * ferramentas nunca contaram nada - inclusive a única que sabe dizer que o sistema NÃO
+ * tinha o que foi pedido.
+ *
+ * Agora o `callTool` o chama uma vez, para toda ferramenta, com a procedência da
+ * resposta. O dono foi explícito sobre por que centralizar (18/08): *"isso vira
+ * comportamento padrão e não depende de disciplina futura."* Um contador chamado dentro
+ * de um `case` é um contador que a próxima ferramenta esquece.
+ *
+ * Nunca bloqueia a resposta: sem sessão ou sem rede, não conta e não quebra - telemetria
+ * que atrasa a ferramenta é telemetria que alguém desliga.
  */
-function countAgentRead(root, component, action, 
+function recordAgentCall(root, call, 
 /** A versão que está reportando - ver `repoStateOf`. Ausente = não reporta estado. */
 cli) {
     void (async () => {
         try {
             const token = await readToken();
-            if (!token || !component)
+            if (!token)
                 return;
             // O slug vem do .lock do sistema instalado - a mesma resolução do sync.
             const dsDir = join(root, "_synthesisui", "ds");
@@ -853,8 +911,10 @@ cli) {
                  */
                 body: JSON.stringify({
                     slug,
-                    component,
-                    action,
+                    tool: toolSlug(call.tool),
+                    source: provenanceAction(call.source),
+                    ...(call.component ? { component: call.component } : {}),
+                    ...(call.action ? { action: call.action } : {}),
                     ...(repo ? { repo } : {}),
                 }),
             });
@@ -912,7 +972,31 @@ async function describeComponent(root, name) {
             break;
     }
     if (!recipe) {
-        return `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`;
+        /**
+         * O EVENTO MAIS VALIOSO DA PLATAFORMA, e até 18/08 ele não era contado.
+         *
+         * Aqui é onde o agente descobre que vai ter que improvisar. A frase já
+         * existia; o que não existia era o REGISTRO - então ninguém sabia quantas
+         * vezes, nem para quê. É este número que decide se compor conhecimento
+         * vale ser construído, e para quais famílias primeiro.
+         */
+        return {
+            /**
+             * ANTES ESTA FRASE TERMINAVA EM "não escreva do zero" E DEIXAVA O AGENTE
+             * SOZINHO - e o `request_component` completava com "siga com a sua solução
+             * alternativa". Juntas, elas diziam à esteira para registrar o improviso
+             * em vez de guiá-lo (dono, 18/08).
+             *
+             * Não ter a receita não é cair no zero: as camadas base existem, e agora
+             * há um playbook que as percorre em ordem. A frase aponta para ele.
+             */
+            body: `This system has no component called "${name}". Run list_components to see what it does have - a near miss still means composing WITH it rather than around it.\n\nIf nothing covers it, do not write from scratch and do not improvise: call playbook { "skill": "compose" }. It walks what this system DOES have, in order - its rules and voice, its tokens, the family this belongs to and what that family requires, and the laws that decide the markup. File request_component along the way so the gap becomes a decision somebody can make.`,
+            source: {
+                kind: "none",
+                reason: "recipe",
+                detail: `no recipe for "${name}"`,
+            },
+        };
     }
     const out = [
         `${name}${recipe.description ? ` - ${recipe.description}` : ""}`,
@@ -1036,53 +1120,168 @@ async function describeComponent(root, name) {
     if (laws.length === 0 && needed.length === 0) {
         out.push("", "No rules govern this component yet. Build with it, and if you find yourself working around it, file request_component with the reasoning.");
     }
-    return out.join("\n");
+    return fromContract(out.join("\n"));
 }
 async function addComponent(root, name) {
     const { table } = await loadSystem(root);
-    if (!table.slug)
-        return "No design system installed here.";
+    if (!table.slug) {
+        return {
+            body: "No design system installed here.",
+            source: { kind: "none", reason: "system", detail: "no system installed" },
+        };
+    }
     const { out } = await capturing(() => component(table.slug, name, { dir: root }));
-    return `${out}\n\nIt is real code in this project now - import it and extend it rather than writing your own.`;
+    return fromContract(`${out}\n\nIt is real code in this project now - import it and extend it rather than writing your own.`);
 }
 // ── The protocol ─────────────────────────────────────────────────────────────
+/**
+ * AS FERRAMENTAS QUE FALAM DE UM COMPONENTE PELO NOME - as únicas cujo alvo é
+ * um slug de receita, e por isso as únicas que gravam o alvo.
+ *
+ * Um valor como `#2563eb` (o alvo de `find_token`) não é nome de componente e
+ * seria recusado pela rota, que valida a coluna como slug. Então o alvo só
+ * viaja quando é um: para o resto, o eixo da procedência é a própria
+ * ferramenta.
+ */
+const BY_COMPONENT = {
+    describe_component: "describe",
+    add_component: "add",
+};
+/**
+ * O ÚNICO PONTO DE INSTRUMENTAÇÃO - e é isto que o dono pediu (18/08): *"vira
+ * comportamento padrão e não depende de disciplina futura."*
+ *
+ * A ferramenta responde, a chamada é registrada com a procedência daquela
+ * resposta, e a linha `Source:` é colada ao texto a partir do MESMO dado que
+ * foi gravado. Não há como o número e a frase discordarem, porque não há duas
+ * fontes.
+ *
+ * Uma ferramenta nova entra no switch e passa a contar sem tocar nesta função.
+ */
 async function callTool(root, name, args, 
-/** A versão que reporta o estado do repo no ping - ver `countAgentRead`. */
+/** A versão que reporta o estado do repo no ping - ver `repoStateOf`. */
 cli) {
+    const answer = await runTool(root, name, args);
+    const gesture = BY_COMPONENT[name];
+    const target = gesture
+        ? String(args.name ?? "")
+            .trim()
+            .toLowerCase()
+        : "";
+    recordAgentCall(root, {
+        tool: name,
+        source: answer.source,
+        ...(gesture ? { action: gesture } : {}),
+        ...(target ? { component: target } : {}),
+    }, cli);
+    return text(withSource(answer), answer.isError);
+}
+/**
+ * O SWITCH PURO - ele resolve a ferramenta e devolve a resposta COM a
+ * procedência. Nenhuma linha dele conta nada: quem instrumenta é `callTool`,
+ * uma vez, para todas.
+ */
+async function runTool(root, name, args) {
     switch (name) {
         case "check_file":
-            return text(await checkFile(root, String(args.path ?? ".")));
+            return checkFile(root, String(args.path ?? "."));
         case "find_token":
-            return text(await findToken(root, String(args.value ?? "")));
+            return findToken(root, String(args.value ?? ""));
         case "system_doctrine":
-            return text(await systemDoctrine(root));
+            return fromContract(await systemDoctrine(root));
         case "list_components":
-            return text(await listComponents(root));
+            return fromContract(await listComponents(root));
         case "describe_component":
-            countAgentRead(root, String(args.name ?? ""), "describe", cli);
-            return text(await describeComponent(root, String(args.name ?? "")));
+            return describeComponent(root, String(args.name ?? ""));
         case "add_component":
-            countAgentRead(root, String(args.name ?? ""), "add", cli);
-            return text(await addComponent(root, String(args.name ?? "")));
+            return 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));
+            return fromContract(await playbook(skill, section));
         }
         case "recipe_vocabulary":
-            return text(await recipeVocabulary());
+            return fromContract(await recipeVocabulary());
         case "validate_recipe": {
             // Same resolution as the batch: an `at` the validator cannot see reads as
             // an empty node and earns a false floor verdict (dono, 01/08).
             const [only] = await resolveAtNodes(root, [
                 { name: String(args.name ?? "this component"), recipe: args.recipe },
             ]);
-            return text(await validateRecipe(String(args.name ?? "this component"), only?.recipe ?? args.recipe));
+            return fromContract(await validateRecipe(String(args.name ?? "this component"), only?.recipe ?? args.recipe));
         }
         case "validate_recipes":
-            return text(await validateRecipes(root, Array.isArray(args.recipes)
+            return fromContract(await validateRecipes(root, Array.isArray(args.recipes)
                 ? args.recipes
                 : []));
+        case "compose_context": {
+            /**
+             * A ORQUESTRAÇÃO - e o que ela reúne é do SISTEMA DELE, com o nosso
+             * esqueleto de julgamento por cima.
+             *
+             * Uma chamada em vez de cinco, e a procedência disto é `composed`: o
+             * primeiro caminho da esteira que emite esse kind, que até aqui existia no
+             * vocabulário e não em resposta nenhuma.
+             */
+            const asked = String(args.family ?? "")
+                .trim()
+                .toLowerCase();
+            const intent = String(args.intent ?? "").trim();
+            if (!isFamily(asked)) {
+                return {
+                    body: noFamilyAnswer(asked || "(nothing)"),
+                    source: {
+                        kind: "none",
+                        reason: "family",
+                        detail: `no family fits "${asked}"`,
+                    },
+                };
+            }
+            const { documents, table, doctrines, requires } = await loadSystem(root);
+            if (documents.length === 0) {
+                return {
+                    body: "No design system installed here, so there is nothing to compose from. Run `synthesisui add <slug>` first - composing against nothing would be inventing.",
+                    source: {
+                        kind: "none",
+                        reason: "system",
+                        detail: "no system installed",
+                    },
+                };
+            }
+            const plan = composePlan({
+                documents,
+                table,
+                rules: doctrines.flatMap((d) => d.rules),
+                /**
+                 * A regra tem a FRASE e o PACOTE em campos separados (`text`,
+                 * `requires`) - mandar a frase sozinha esconderia o que instalar, e
+                 * mandar só o pacote esconderia o porquê.
+                 */
+                requires: requires.map((r) => ({
+                    rule: r.requires ? `${r.requires} - ${r.text}` : r.text,
+                })),
+                family: asked,
+                intent,
+            });
+            /** O checklist é servido; sem rede o resto do plano continua valendo. */
+            const answer = await askCatalogue("vocabulary");
+            const v = answer.ok
+                ? answer.body
+                : null;
+            const vocabulary = v
+                ? {
+                    floor: v.floor?.[asked] ?? [],
+                    checklist: v.checklist?.[asked] ?? [],
+                }
+                : null;
+            return {
+                body: renderPlan(plan, vocabulary),
+                source: {
+                    kind: "composed",
+                    detail: `${asked} · ${plan.siblings.length} recipe${plan.siblings.length === 1 ? "" : "s"} and ${plan.tokens.length} token${plan.tokens.length === 1 ? "" : "s"} from this system`,
+                },
+            };
+        }
         case "request_component": {
             const r = await fileRequest(root, {
                 kind: "component",
@@ -1091,7 +1290,7 @@ cli) {
                 considered: args.considered ? String(args.considered) : undefined,
                 file: args.file ? String(args.file) : undefined,
             });
-            return text(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it - keep building with your workaround, and say in your summary that the request exists.`);
+            return fromContract(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it.\n\nNow build it properly rather than working around it: playbook { "skill": "compose" } walks the layers this system already declares, so what you hand back matches it even without a recipe. Say in your summary that the request exists, and which parts were composed rather than taken from the system.`);
         }
         case "refresh_system": {
             /**
@@ -1111,10 +1310,10 @@ cli) {
              */
             const slug = await installedSlug(root);
             if (!slug)
-                return text("No system installed here that belongs to a dashboard row, so there is nothing to refresh. `synthesisui add <slug>` installs one; an adopted system is described here and owned elsewhere.");
+                return fromContract("No system installed here that belongs to a dashboard row, so there is nothing to refresh. `synthesisui add <slug>` installs one; an adopted system is described here and owned elsewhere.");
             const token = await readToken();
             if (!token)
-                return text("Not signed in, so nothing could be sent. A person has to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.");
+                return fromContract("Not signed in, so nothing could be sent. A person has to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.");
             const { out } = await capturing(() => remeasure({
                 root,
                 base: resolveRegistry(),
@@ -1137,7 +1336,7 @@ cli) {
             const behind = pinned && pinned !== VERSION ? pinned : null;
             const said = out.trim() ||
                 "Nothing was reported by the refresh - which means it found nothing to measure.";
-            return text(behind
+            return fromContract(behind
                 ? `${said}\n\nUPDATE THE DESIGN SYSTEM BEFORE CONTINUING.\nThe check that runs after your writes is pinned to ${behind} and these tools are ${VERSION}.\n\n  npx synthesisui@latest connect\n\nAsk the person, run it for them, and then say this: close and reopen the editor. The hook and the tools only rewire on a new session, so nothing you write before that is checked by the reader you are holding.`
                 : said);
         }
@@ -1159,7 +1358,7 @@ cli) {
                 file: args.file ? String(args.file) : undefined,
                 ...(area ? { area } : null),
             });
-            return text(area
+            return fromContract(area
                 ? `Filed as ${r.id} and routed to the synthesisui platform team - the system's contract already promises this and the shipped css does not deliver it. No one needs to act: it closes itself when an update lands. Keep the quiet base meanwhile.`
                 : `Filed as ${r.id}. Do not add the token yourself - the request shows up in \`synthesisui doctor\` for a person to decide.`);
         }
@@ -1179,10 +1378,14 @@ cli) {
                 considered: args.considered ? String(args.considered) : undefined,
                 file: args.file ? String(args.file) : undefined,
             });
-            return text(`Filed as ${r.id}. Do not adopt the convention as if it were a rule - it shows up in \`synthesisui doctor\` and travels to the system's queue, for the owner to make it a rule or decline it.`);
+            return fromContract(`Filed as ${r.id}. Do not adopt the convention as if it were a rule - it shows up in \`synthesisui doctor\` and travels to the system's queue, for the owner to make it a rule or decline it.`);
         }
         default:
-            return text(`No tool named ${name}.`, true);
+            return {
+                body: `No tool named ${name}.`,
+                source: { kind: "none", reason: "tool", detail: "unknown tool" },
+                isError: true,
+            };
     }
 }
 /**

package/dist/compose-context.js

@@ -0,0 +1,210 @@
+/**
+ * O CONTEXTO MÍNIMO PARA CONSTRUIR ALGO QUE O SISTEMA NÃO TEM.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * AS DUAS FONTES, E A PROPORÇÃO ENTRE ELAS SE INVERTE SOZINHA
+ *
+ * O material que enche este contexto é DELE - os tokens que as receitas dele já
+ * usam, as regras que ele declarou, as bibliotecas que o repositório dele
+ * carrega. É isso que faz o componente novo nascer parecido com o sistema dele
+ * em vez de parecido com o nosso gosto.
+ *
+ * O que é NOSSO é pequeno de propósito e não fala de nenhum componente
+ * específico: as sete famílias, o checklist de cada uma e as leis de marcação.
+ * Sem essa metade, um sistema de dois componentes - e existem quatro deles em
+ * produção, medido em 18/08 - não teria nada a oferecer justamente a quem mais
+ * precisa de orientação.
+ *
+ * Sistema maduro: "o seu input usa estes sete tokens, use os mesmos" (paridade).
+ * Sistema novo: "um campo precisa destas cinco coisas, o seu sistema ainda não
+ * nomeia três delas" (orientação, com a lacuna declarada).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * A FAMÍLIA VEM DE QUEM PEDE, e a plataforma valida (decisão do dono, 18/08)
+ *
+ * Quem chama esta ferramenta é um modelo que acabou de ler o pedido em linguagem
+ * natural. Ele classifica melhor que qualquer heurística de palavras que a gente
+ * escrevesse aqui, e classificar com IA hospedada gastaria Ink para responder o
+ * que já foi respondido do outro lado da chamada.
+ *
+ * Então o agente informa a família, a gente confere contra o contrato, e quando
+ * ela não é nenhuma das sete isso não é erro: é uma lacuna de FAMÍLIA, que é uma
+ * decisão diferente de um componente faltando.
+ */
+/** As sete que o contrato conhece - o mesmo enum de `componentPreviewKind`. */
+export const FAMILIES = [
+    "action",
+    "control",
+    "field",
+    "surface",
+    "pill",
+    "indicator",
+    "text",
+];
+export function isFamily(value) {
+    return FAMILIES.includes(value);
+}
+/**
+ * OS TOKENS QUE ESTA FAMÍLIA JÁ USA, lidos das receitas dela.
+ *
+ * Uma referência de token num documento é `{color.semantic.canvas}` - a mesma
+ * forma que o compilador resolve. Então "quais tokens um campo usa neste
+ * sistema" é uma pergunta que o próprio documento responde, sem tabela nossa e
+ * sem palpite.
+ *
+ * MEDIDO no signalui (37 componentes, 74 referências no total): field 37,
+ * surface 37, control 33, action 24, pill 17, text 15, indicator 12. O corte por
+ * volume é modesto num sistema pequeno - o valor aqui não é economia de
+ * contexto, é PARIDADE: o agente copia o que existe em vez de escolher.
+ */
+export function tokensOfFamily(documents, family) {
+    const refs = new Set();
+    for (const doc of documents) {
+        const components = doc
+            .components;
+        if (!components)
+            continue;
+        for (const recipe of Object.values(components)) {
+            if (recipe?.preview?.kind !== family)
+                continue;
+            for (const ref of JSON.stringify(recipe).match(/\{[a-z0-9.]+\}/gi) ??
+                []) {
+                /**
+                 * `{onPressedChange}` e afins aparecem no mesmo formato e NÃO são
+                 * tokens - são nomes de prop que a receita cita. Um token tem caminho:
+                 * família, e depois pelo menos um degrau.
+                 */
+                if (ref.includes("."))
+                    refs.add(ref);
+            }
+        }
+    }
+    return [...refs].sort();
+}
+/** As receitas desta família que o sistema já tem - de onde copiar. */
+export function recipesOfFamily(documents, family) {
+    const out = [];
+    for (const doc of documents) {
+        const components = doc
+            .components;
+        if (!components)
+            continue;
+        for (const [name, recipe] of Object.entries(components)) {
+            if (recipe?.preview?.kind === family) {
+                out.push({
+                    name,
+                    ...(recipe.description ? { description: recipe.description } : null),
+                });
+            }
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * O VALOR DE CADA REFERÊNCIA, quando a tabela o conhece.
+ *
+ * `{radius.md}` sozinho não diz nada a quem vai escrever css; `{radius.md} =
+ * 0.5rem` diz. A tabela de tokens é a mesma que o `find_token` consulta, então
+ * a resposta aqui e a resposta dele nunca divergem.
+ */
+export function valueOf(table, ref) {
+    const path = ref.slice(1, -1);
+    /** `color.semantic.canvas` -> `--ds-color-semantic-canvas`. */
+    const name = `--ds-${path.replace(/\./g, "-")}`;
+    return table.byName.get(name) ?? null;
+}
+/**
+ * A MONTAGEM - pura, e é por isso que ela mora fora do handler.
+ *
+ * O handler faz I/O (`loadSystem`, a rede do catalogue). O que decide o que
+ * entra no contexto é isto, e é o que um spec consegue exercer com um documento
+ * de verdade sem subir nada.
+ */
+export function composePlan(input) {
+    const refs = tokensOfFamily(input.documents, input.family);
+    return {
+        family: input.family,
+        intent: input.intent,
+        siblings: recipesOfFamily(input.documents, input.family),
+        tokens: refs.map((ref) => ({ ref, value: valueOf(input.table, ref) })),
+        rules: [...input.rules],
+        requires: [...input.requires],
+    };
+}
+/**
+ * O PLANO COMO O AGENTE O LÊ - e a ordem é a das camadas, não a da comodidade.
+ *
+ * Cada bloco diz de onde veio: o que é do sistema dele, o que é checklist nosso,
+ * e o que ninguém decidiu ainda. É a mesma gramática da linha `Source:` que toda
+ * resposta carrega, um nível abaixo - e é o que permite ao agente relatar
+ * procedência por parte em vez de por resposta.
+ */
+export function renderPlan(plan, 
+/** O checklist e o piso desta família, servidos do catálogo. `null` sem rede. */
+vocabulary) {
+    const out = [
+        `COMPOSING: ${plan.intent || plan.family}`,
+        `FAMILY: ${plan.family} - every part below answers to this family's checklist.`,
+        "",
+    ];
+    out.push("── FROM THIS SYSTEM ────────────────────────────────────────");
+    if (plan.siblings.length > 0) {
+        out.push(`Recipes in this family, to copy from rather than to choose against (${plan.siblings.length}):`, ...plan.siblings.map((s) => `  ${s.name}${s.description ? ` - ${s.description}` : ""}`));
+    }
+    else {
+        out.push("This system has NO recipe in this family yet. Nothing here to copy, so", "every decision below is one you are making for the first time - name them", "in your summary, and file what the system should have named.");
+    }
+    out.push("");
+    if (plan.tokens.length > 0) {
+        out.push(`Tokens those recipes already use (${plan.tokens.length}) - use these before any literal:`, ...plan.tokens.map((t) => `  ${t.ref}${t.value ? ` = ${t.value}` : " (name declared, value not on disk)"}`));
+    }
+    else {
+        out.push("No token is used by this family yet. Ask `find_token` for each value you", "need, and file `request_token` for the ones nothing holds - never invent a name.");
+    }
+    if (plan.rules.length > 0) {
+        out.push("", `Rules - maximum authority, ${plan.rules.length} of them:`, ...plan.rules.map((r) => `  - ${r}`));
+    }
+    if (plan.requires.length > 0) {
+        out.push("", "Packages this system says the project needs:", ...plan.requires.map((r) => `  - ${r.rule}`));
+    }
+    out.push("", "── THE FLOOR FOR THIS FAMILY ───────────────────────────────");
+    if (vocabulary) {
+        if (vocabulary.floor.length > 0) {
+            out.push("Below this it cannot be told apart from the page:");
+            out.push(...vocabulary.floor.map((f) => `  ${f}`));
+        }
+        out.push("", "Work this list and say which items this system's own recipes answer:", ...vocabulary.checklist.map((c) => `  - ${c}`));
+    }
+    else {
+        out.push("The checklist is served from the platform and could not be reached right", "now. Everything above still holds - fetch it with `recipe_vocabulary`", "before you call the component finished.");
+    }
+    out.push("", "── WHAT IS NOT HERE ────────────────────────────────────────", "The laws that decide the markup (which tag, whose layout wins, why", "accessibility moves the ink) are one fetch away and not repeated here:", '  playbook { "skill": "compose", "section": "path-2-layer-3-the-laws-that-decide-the-markup" }', "", "The voice - how this product speaks - is not in this answer either. Call", "`system_doctrine` before writing any user-facing copy inside this component.", "", "When you are done: `validate_recipe` if you are writing one, then", "`request_component` for what the system should have had, and report which", "parts came from the system and which you composed.");
+    return out.join("\n");
+}
+/**
+ * A RESPOSTA QUANDO A FAMÍLIA NÃO É NENHUMA DAS SETE.
+ *
+ * Não é erro e não é uma lista de sugestões parecidas: é um fato sobre o
+ * contrato, e o pedido de quem o lê é diferente do pedido de um componente. Um
+ * gráfico, um mapa, uma grade de calendário não são `surface` mal classificado -
+ * forçá-los ali produziria um piso que não significa nada.
+ */
+export function noFamilyAnswer(asked) {
+    return [
+        `"${asked}" is not one of the seven families this contract can draw: ${FAMILIES.join(", ")}.`,
+        "",
+        "That is a real answer, not a rejection. Two things are true at once:",
+        "",
+        "  1. Everything ABOVE the family layer still holds in full - the system's",
+        "     rules, its tokens, and the laws of markup. Ask `find_token` per value,",
+        "     `system_doctrine` for the rules, and fetch the laws chapter of the",
+        "     compose playbook.",
+        "  2. What is missing is a KIND, not a component - and that is a different",
+        "     decision for the system's owner. File it:",
+        "     request_component with what the thing is and why no family fits.",
+        "",
+        "Then decompose: parts of it probably DO have families. A region that holds",
+        "things is a surface, a control inside it is a control - ask again for those",
+        "parts, and compose the rest without a family, saying so.",
+    ].join("\n");
+}

package/dist/skill-compose.js

@@ -0,0 +1,22 @@
+/**
+ * O STUB DA SKILL DE COMPOSIÇÃO - o corpo é SERVIDO, como os outros três.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * POR QUE ESTA SKILL EXISTE (dono, 18/08)
+ *
+ * As três primeiras cobrem trazer um sistema para dentro e mantê-lo. Nenhuma
+ * cobria o gesto mais comum do dia a dia: alguém pede um componente que o
+ * sistema não tem.
+ *
+ * E o que a plataforma respondia nesse caso eram duas frases, medidas:
+ * `describe_component` dizia *"não escreva do zero"* e `request_component`
+ * dizia, na frase seguinte, *"siga com a sua solução alternativa"*. Ou seja, a
+ * esteira registrava que o agente improvisou em vez de guiar a composição - o
+ * oposto de uma hierarquia de conhecimento.
+ *
+ * A tese do dono: não ter a receita não é cair no zero. As camadas base
+ * existem - tokens, regras, a família e o que o tipo dela exige, as leis de
+ * marcação - e compor a partir delas é tão valioso quanto ter a receita pronta.
+ */
+export const COMPOSE_SKILL_PATH = ".claude/skills/sui-compose/SKILL.md";
+export const COMPOSE_SKILL = '---\nname: sui-compose\ndescription: Build ANY UI element the installed design system has no recipe for - without inventing values, tags or accessibility. Use whenever you are about to write a UI element from scratch, when `describe_component` answers that the system does not have it, or when what was asked for is a composite nobody has written yet - whatever it is called (an editor, a palette, a table, a chart, a layout region: the playbook does not care which). Walks the layers the system DOES have, in order, decomposes the request into families, and declares what it could not cover.\n---\n\n# Compose what the system does not have - served live\n\nThis playbook is served from the platform, not shipped in this file - it is\nalways current, and your context only carries the step you are on.\n\n1. Call the `playbook` tool on the `synthesisui` MCP server with\n   { "skill": "compose" } - you get the framing and a table of contents.\n2. Fetch ONLY the chapter for the step you are on:\n   { "skill": "compose", "section": "<id from the toc>" }. Never fetch more\n   than the current step needs.\n3. Follow it exactly. When the step is done, fetch the next chapter.\n\nThe first chapter tells you which of the two paths you are on - the system has\na recipe, or nobody has written one yet - and the rest walk the layers in order.\n\nIf the tool answers that you are not signed in, run `npx synthesisui login`\nin the terminal and call it again. If the `synthesisui` MCP server is not\navailable at all, run `npx synthesisui connect`, restart the session, and\ninvoke this skill again.\n';

package/dist/skills.js

@@ -1,4 +1,5 @@
 import { ADAPT_SKILL, ADAPT_SKILL_PATH } from "./skill-adapt.js";
+import { COMPOSE_SKILL, COMPOSE_SKILL_PATH } from "./skill-compose.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "./skill-import.js";
 import { INIT_SKILL, INIT_SKILL_PATH } from "./skill-init.js";
 /**
@@ -36,4 +37,20 @@ export const SKILLS = [
         label: "/sui-adapt",
         what: "one component against the system, and what to do about it",
     },
+    /**
+     * A DE CONSTRUÇÃO, e ela é a que responde ao pedido mais comum de todos:
+     * "faz um componente X" quando o sistema não tem X.
+     *
+     * As três acima são sobre o sistema - trazer, manter, conferir. Esta é sobre o
+     * TRABALHO de quem usa o sistema, e é a única que roda todo dia. Ela existe
+     * porque a resposta anterior a esse pedido era o agente improvisar sozinho: a
+     * esteira dizia "não escreva do zero" e, na frase seguinte, "siga com a sua
+     * solução alternativa" (dono, 18/08).
+     */
+    {
+        path: COMPOSE_SKILL_PATH,
+        source: COMPOSE_SKILL,
+        label: "/sui-compose",
+        what: "build what the system does not have, layer by layer",
+    },
 ];

package/package.json

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