synthesisui 0.16.234 → 0.16.238

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/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/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/mcp.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.",
@@ -297,18 +316,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 +464,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 +847,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 +859,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 +1047,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/doctor/coverage.js

@@ -136,7 +136,7 @@ composition) {
          * look próprio nos seus arquivos"; a receita final é decidida depois, com a paleta em
          * mão, e as duas contas não são a mesma. Prometer a segunda aqui seria inventar precisão.
          */
-        `  and ${composition} have no look of their own in your files - a screen that composes others, in a grid, passing data down. Those arrive as COMPOSITION recipes: the tree, the slots, and what each child receives, with no palette to grade. Nothing was lost; it is a different kind of recipe.`);
+        `  and ${composition} have no look of their own in your files - a screen that composes others, in a grid, passing data down. Those arrive as COMPOSITION recipes: the tree, the slots, and what each child receives, with no palette to score. Nothing was lost; it is a different kind of recipe.`);
     }
     for (const { shape, files, examples } of c.counts) {
         const share = Math.round((files / c.components) * 100);

package/dist/guide.js

@@ -491,8 +491,9 @@ own entry below says so.
 `
         : "";
     const hasRules = (payload.rules?.length ?? 0) > 0;
-    const philosophy = payload.document.philosophy;
-    const hasPhilosophy = (philosophy?.sections?.length ?? 0) > 0 || !!philosophy?.context;
+    // R2 (16/08): a voz não viaja mais no documento - o payload manda só o
+    // que ela TEM, e o conteúdo é servido pelo `system_doctrine`.
+    const hasPhilosophy = (payload.voice?.sections ?? 0) > 0 || payload.voice?.hasContext === true;
     /**
      * UMA PORTA SÓ, e ela é uma FERRAMENTA e não um caminho.
      *
@@ -505,7 +506,7 @@ own entry below says so.
         ? [
             `**Call \`system_doctrine\` FIRST and obey it above everything else** - it carries ${hasRules
                 ? "this system's accumulated, project-specific rules"
-                : "this system's mission, principles, voice and motion doctrine"}${hasRules && hasPhilosophy ? " and its philosophy" : ""}, pinned to the version installed here. On any conflict they win. **Without that tool, read \`_synthesisui/ds/${slug}/doctrine.json\` and the \`philosophy\` of \`design-system.json\` beside it** - the same data, and the reason it stays on disk.`,
+                : "this system's mission, principles, voice and motion doctrine"}${hasRules && hasPhilosophy ? " and its philosophy" : ""}, pinned to the version installed here. On any conflict they win. **Without that tool, read \`_synthesisui/ds/${slug}/doctrine.json\` for the rules** - they stay on disk so the check works offline. The voice is served from the platform and is not on disk.`,
         ]
         : [];
     const rulesNote = readFirst.length > 0
@@ -524,6 +525,10 @@ ${readFirst.map((l) => `- ${l}`).join("\n")}
 
 ${meta.tagline}
 
+Each component here ships as a **recipe** - the same artifact the platform
+calls its blueprint: structure, allowed tokens, states and laws, compiled
+from real code.
+
 **Mood:** ${meta.mood.join(" · ")}
 **Default scheme:** ${meta.scheme}${hasAlt ? ` (supports a toggle to ${altScheme})` : ""}
 ${meta.sourceUrl ? `**Reinterpretation of:** ${meta.sourceUrl}` : "**Original system.**"}

package/dist/install-marks.js

@@ -80,7 +80,7 @@
  * Zero ocorrências no sistema real medido (todos os headings dele estão aninhados, e o `children > 0`
  * já os pegava), então para ele o `upgrade` é no-op. A marca é sobre o caso geral.
  */
-export const MATERIALISER_SINCE = "0.16.233";
+export const MATERIALISER_SINCE = "0.16.237";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *