synthesisui 0.16.359 → 0.16.361

package/dist/agent-wiring.js

@@ -1,7 +1,12 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 const HOOK_MATCHER = "Write|Edit|MultiEdit";
-const exists = (p) => access(p).then(() => true, () => false);
+/**
+ * Exportado porque a REGRA é uma só: a pasta de uma ferramenta é a evidência de que ela é usada, e
+ * a mesma evidência decide o MCP daqui e a casa do bloco em `claude-md.ts`. Duas cópias deste
+ * predicado seriam duas chances de as duas decisões divergirem.
+ */
+export const exists = (p) => access(p).then(() => true, () => false);
 async function readJson(path) {
     const raw = await readFile(path, "utf8").catch(() => "");
     if (!raw.trim())

package/dist/claude-md.js

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { hasHook } from "./agent-wiring.js";
+import { exists, hasHook } from "./agent-wiring.js";
 import { declaredReference } from "./group-role.js";
 import { recallAvailable } from "./memory/availability.js";
 const START = "<!-- synthesisui:start -->";
@@ -573,10 +573,11 @@ _Block managed by the CLI - do not edit by hand; run \`synthesisui ${onlyAdopted
  */
 const HOMES = [
     { path: "CLAUDE.md" },
-    { path: "AGENTS.md" },
+    { path: "AGENTS.md", bornWhen: ".codex" },
     {
         path: ".cursor/rules/synthesisui.mdc",
         frontmatter: "---\ndescription: Design system rules - read before writing UI\nalwaysApply: true\n---\n\n",
+        bornWhen: ".cursor",
     },
 ];
 export async function syncClaudeMd(projectRoot) {
@@ -594,15 +595,18 @@ export async function syncClaudeMd(projectRoot) {
             existing = null;
         }
         /**
-         * O ARQUIVO NOVO SÓ NASCE PARA O CLAUDE.md.
+         * O ARQUIVO NOVO NASCE QUANDO O REPOSITÓRIO JÁ MOSTROU QUEM ELE USA - ver `bornWhen`.
          *
-         * Criar `AGENTS.md` num repo que nunca teve um é decidir por outra pessoa qual agente ela usa, e
-         * um arquivo que apareceu sozinho na raiz é a primeira coisa que alguém apaga com raiva. Nos
-         * outros dois a regra é: se o arquivo existe, o bloco entra e se mantém atualizado; se não
-         * existe, não inventamos um.
+         * `CLAUDE.md` sem condição, porque é a casa que a gente cria num repo que não tem nenhuma. Os
+         * outros dois só quando a pasta da ferramenta está lá: criar `AGENTS.md` num repo que só usa
+         * Claude Code continua sendo decidir por outra pessoa qual agente ela usa, e um arquivo que
+         * apareceu sozinho na raiz é a primeira coisa que alguém apaga com raiva.
          */
         if (existing === null) {
-            if (home.path !== "CLAUDE.md")
+            const authorised = home.path === "CLAUDE.md" ||
+                (home.bornWhen != null &&
+                    (await exists(join(projectRoot, home.bornWhen))));
+            if (!authorised)
                 continue;
             await mkdir(dirname(path), { recursive: true }).catch(() => { });
             await writeFile(path, `${home.frontmatter ?? ""}${region}\n`, "utf8");

package/dist/commands/align.js

@@ -676,12 +676,21 @@ export function renderNextStep(next, freshSession) {
      *  pessoa tivesse perdido uma opção da tela. */
     if (next.open?.length)
         lines.push(...bodyWrapped(next.open.length === 1
-            ? "That flag lets it write without asking each time. Drop it to approve every change yourself."
-            : "Those flags let it write without asking each time. Drop them to approve every change yourself.").map(paint.dim));
-    if (freshSession)
-        lines.push(...bodyWrapped(freshSession.mcp
-            ? "A new session is what loads the skills and tools just installed, and the project's tools ask for approval once - say yes."
-            : "A new session is what loads the skills just installed.").map(paint.dim));
+            ? "Drop the flag to approve each write yourself."
+            : "Drop the flags to approve each write yourself.").map(paint.dim));
+    if (freshSession) {
+        const list = freshSession.loads;
+        const said = list.length === 0
+            ? "and"
+            : list.length === 1
+                ? list[0]
+                : `${list.slice(0, -1).join(", ")} and ${list.at(-1)}`;
+        lines.push(...bodyWrapped(list.length === 0
+            ? "A new session reads the wiring this run changed."
+            : `This run moved ${said}, and a new session is what reads ${list.length === 1 ? "it" : "them"}.`).map(paint.dim));
+        if (freshSession.mcp)
+            lines.push(...bodyWrapped("The project's tools ask for approval once - say yes.").map(paint.dim));
+    }
     return lines.join("\n");
 }
 /**

package/dist/commands/connect.js

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { wireAgent } from "../agent-wiring.js";
 import { blockHomes, syncClaudeMd } from "../claude-md.js";
 import { resolveRegistry } from "../config.js";
-import { body, paint, section, snippet } from "../output.js";
+import { body, bodyWrapped, paint, section, snippet } from "../output.js";
 import { readShellAnswer, rememberShellNo } from "../shell-answer.js";
 import { existingRc, hasHook, pinnedInHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell-hook.js";
 import { SKILLS } from "../skills.js";
@@ -173,8 +173,12 @@ version) {
         return;
     }
     console.log("");
-    console.log(body("Your editor tells you when this repo drifts, once a session. Your terminal does not, and that is where most people notice something is stale."));
-    console.log(body(paint.faint(`Adding it writes one block to ${rc}. It stays silent when nothing is wrong, never blocks your prompt, and checks at most once an hour.`)));
+    /**
+     * A OFERTA EM DUAS LINHAS - eram cinco, e ela ficava entre a lista do que foi instalado e a ação
+     * recomendada, empurrando para baixo a única coisa que a pessoa procurava. O que ela precisa dizer
+     * é o que ganha, o que a gente escreve e onde: nada disso saiu.
+     */
+    console.log(bodyWrapped(`Your terminal can warn you when this repo drifts - one block in ${rc}, silent unless something is wrong, at most once an hour.`).join("\n"));
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         console.log(body(paint.blue("  npx synthesisui@latest connect --shell")));
         return;
@@ -228,6 +232,37 @@ export async function connect(opts) {
     // after them, not before.
     const contract = await syncClaudeMd(root);
     console.log(section("Connected"));
+    /**
+     * A LISTA DA TELA, JUNTADA ANTES DE IMPRIMIR - e é isto que faz a rodada silenciosa caber numa
+     * linha.
+     *
+     * O QUE O CLIENTE GANHA: ele lê o que MUDOU, e o que não mudou vira uma linha só. Medido em 03/09
+     * na segunda rodada deste comando: 41 linhas na tela, das quais 10 diziam `already had it` /
+     * `already current` - um quarto da tela informando ausência de novidade, exatamente entre a pessoa
+     * e a única instrução que ela procurava.
+     *
+     * A DISTINÇÃO NÃO SE PERDE: cada peça que mudou continua nomeada, com o seu detalhe embaixo. O que
+     * colapsa é o silêncio, que não tem detalhe para dar.
+     */
+    const rows = [];
+    const row = (moved, line, under) => {
+        rows.push({ moved, line, ...(under ? { under } : {}) });
+    };
+    const flush = () => {
+        for (const r of rows) {
+            if (!r.moved)
+                continue;
+            console.log(body(r.line));
+            if (r.under)
+                console.log(snippet([r.under]));
+        }
+        const quiet = rows.filter((r) => !r.moved).length;
+        if (quiet === 0)
+            return;
+        console.log(body(paint.dim(quiet === rows.length
+            ? "· nothing to change - this environment is already current"
+            : `· ${quiet} other ${quiet === 1 ? "piece" : "pieces"} already current`)));
+    };
     /**
      * E O QUE FALTA, DITO EM VOZ ALTA - porque este comando estava mentindo por omissão.
      *
@@ -240,45 +275,61 @@ export async function connect(opts) {
      * `CLAUDE.md`, achou o bloco vazio, e não havia nada dizendo que faltava um comando. Lacuna
      * silenciosa é o que faz um produto correto parecer quebrado.
      *
-     * E SÃO DOIS CAMINHOS, não um. A primeira versão desta mensagem mandava `add <slug>` e só - o que
-     * desorienta justamente quem acabou de rodar `connect` num projeto que AINDA NÃO TEM sistema, que é
-     * a primeira corrida e o caso mais comum. Para essa pessoa o passo seguinte é a skill que este mesmo
-     * comando acabou de instalar, e não um comando de terminal. Quem já tem sistema na plataforma é o
-     * outro caso, e ele também é dito.
+     * E ELE DIZ A LACUNA, NÃO O QUE FAZER - corrigido em 03/09, com o dono lendo a própria tela.
+     *
+     * Ele carregava os dois caminhos ("ask the agent for `/sui-init`" e "`synthesisui add <slug>`"), e
+     * o resultado era UMA TELA COM DUAS INSTRUÇÕES para o mesmo passo: esta linha mandava pedir uma
+     * slash command, e a ação recomendada, quinze linhas abaixo, mandava dizer uma frase. Quem lê não
+     * tem como saber qual das duas é a certa.
+     *
+     * E A FRASE É A CERTA, por decisão de produto (dono, 03/09): *"as skills são chamadas de acordo
+     * com a necessidade que o Claude vai encontrando, não por comando nosso diretamente"*. Nomear
+     * `/sui-init` ensina o cliente a dirigir o agente por comando, que é o oposto de como a esteira
+     * foi desenhada - e amarra a instrução ao nome de uma skill que pode ser dividida amanhã.
+     *
+     * `nextStepFor` JÁ COBRE OS DOIS CAMINHOS, e com a mesma distinção: medido sem sistema instalado
+     * leva a `list --mine` + `add <slug>`; nunca medido leva à frase. Então isto para de repeti-los e
+     * fica com o que só ele diz - a CONSEQUÊNCIA da lacuna, que é o que fez alguém perder tempo em
+     * 20/08 achando o bloco do `CLAUDE.md` vazio sem nada explicando por quê.
      */
     const anyInstalled = (await installedSlugs(root).catch(() => [])).length > 0;
     if (!anyInstalled)
-        console.log(body("· no design system installed here yet - the agent has no index, and memory has nothing to belong to.\n  This repo has none yet:  ask the agent for `/sui-init`, or `/sui-import-ds` to turn this project into one.\n  You already have one:     `synthesisui list` shows them, `synthesisui add <slug>` brings it in."));
+        console.log(bodyWrapped("· no design system installed here yet - the agent has no index, and memory has nothing to belong to.").join("\n"));
     /**
      * O QUE ESTE CLI REESCREVEU NA PASTA DO SISTEMA - dito primeiro, porque é o que a pessoa não sabia
      * que estava devendo. Ela rodou `connect` para atualizar a fiação; os arquivos do install estarem
      * velhos era invisível, e o `upgrade` não alcançava (ver `refreshInstall`).
      */
     if (refreshed)
-        console.log(body(`✓ _synthesisui/ds/${refreshed.slug}/  rewritten by this CLI${refreshed.was
+        row(true, `✓ _synthesisui/ds/${refreshed.slug}/  rewritten by this CLI${refreshed.was
             ? ` - it was written by ${refreshed.was}`
-            : " - it carried no CLI version, so it predates this"}`));
+            : " - it carried no CLI version, so it predates this"}`);
     if (want.hook) {
-        console.log(body(wired.hook === "added"
-            ? "✓ .claude/settings.json  the check now runs after every write"
-            : wired.hook === "updated"
-                ? /**
-                   * A LINHA QUE FALTAVA, e a ausência dela fazia o comando mentir: rodando o 0.16.157, a
-                   * saída dizia "already had it" e imprimia `npx synthesisui@0.16.153 hook` embaixo
-                   * (dono, 06/08). Quem lê "already had it" fecha o terminal.
-                   */
-                    `✓ .claude/settings.json  the check moved from ${wired.was?.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? "an older version"} to this one`
-                : "· .claude/settings.json  already had it"));
-        console.log(snippet([wired.command]));
+        row(wired.hook !== "already there", (() => {
+            return wired.hook === "added"
+                ? "✓ .claude/settings.json  the check now runs after every write"
+                : wired.hook === "updated"
+                    ? /**
+                       * A LINHA QUE FALTAVA, e a ausência dela fazia o comando mentir: rodando o 0.16.157, a
+                       * saída dizia "already had it" e imprimia `npx synthesisui@0.16.153 hook` embaixo
+                       * (dono, 06/08). Quem lê "already had it" fecha o terminal.
+                       */
+                        `✓ .claude/settings.json  the check moved from ${wired.was?.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? "an older version"} to this one`
+                    : "· .claude/settings.json  already had it";
+        })(), wired.command);
         /**
          * A SEGUNDA COSTURA, dita por nome. As onze ferramentas MCP são PULL e o hook de escrita roda
          * DEPOIS de uma escrita - nenhum dos dois chega a tempo de dizer "você não está logado nesta
          * máquina" ou "este sistema não sabe de onde foi medido". O `SessionStart` é o único que chega.
          */
         if (wired.session !== "skipped")
-            console.log(body(wired.session === "already there"
+            row(wired.session !== "already there", wired.session === "already there"
                 ? "· .claude/settings.json  the session check was already there"
-                : `✓ .claude/settings.json  every session now opens with what this environment is missing${wired.session === "updated" ? ", pointed at this version" : ""}`));
+                : wired.session === "updated"
+                    ? /** A distinção `added` x `updated` vale desde 06/08: um estado que não se
+                       *  distingue de "nada a fazer" faz a instrução de atualizar mentir. */
+                        "✓ .claude/settings.json  the session check moved to this one"
+                    : "✓ .claude/settings.json  each session opens with what is missing");
     }
     /**
      * OS CAMINHOS DE MCP, POR NOME - e o número vem da LISTA, não da minha memória.
@@ -289,13 +340,13 @@ export async function connect(opts) {
      */
     if (want.mcp && wired.mcp !== "skipped") {
         for (const one of wired.mcp)
-            console.log(body(one.status === "added"
-                ? `✓ ${one.path.padEnd(22)} ${MCP_TOOL_COUNT} tools, so the agent can ask instead of guess`
+            row(one.status !== "already there", one.status === "added"
+                ? `✓ ${one.path.padEnd(22)} ${MCP_TOOL_COUNT} tools the agent can ask`
                 : one.status === "updated"
                     ? /** Uma entrada pinada antes de o MCP flutuar ficava pinada para sempre - nenhum
                        *  `connect` a soltava, e o agente segurava um leitor velho sem saber. */
-                        `✓ ${one.path.padEnd(22)} unpinned - it now follows the published reader`
-                    : `· ${one.path.padEnd(22)} already had it`));
+                        `✓ ${one.path.padEnd(22)} unpinned - it follows the published reader`
+                    : `· ${one.path.padEnd(22)} already had it`);
     }
     /**
      * ONDE O BLOCO CAIU, DITO POR NOME.
@@ -311,7 +362,7 @@ export async function connect(opts) {
      */
     for (const home of await blockHomes(root)) {
         const moved = contract.changed.includes(home);
-        console.log(body(`${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
+        row(moved, `${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
             ? home === "CLAUDE.md"
                 ? /**
                    * A FRASE DIZ O QUE O BLOCO CARREGA, e ela descrevia um conteúdo que não existia.
@@ -323,10 +374,10 @@ export async function connect(opts) {
                     contract.count === 0
                         ? "how to turn this repo into your system"
                         : "rewritten for what is installed"
-                : "the same rules, where this agent reads them"
+                : "the same rules, where this agent reads"
             : contract.count === 0
                 ? "already says how to start"
-                : "already says what is installed"}`));
+                : "already says what is installed"}`);
     }
     /**
      * The fourth layer, and the one that had no installer at all: the import
@@ -369,21 +420,26 @@ export async function connect(opts) {
         if (had == null)
             continue;
         await rm(dir, { recursive: true, force: true }).catch(() => { });
-        console.log(body(`✕ /${legacy.padEnd(21)} removed - renamed to /sui-import-ds`));
+        row(true, `✕ /${legacy.padEnd(21)} removed - renamed to /sui-import-ds`);
     }
+    /** Se ALGUMA skill mudou nesta rodada - é o que autoriza a frase da sessão nova a citá-las. */
+    let skillsMoved = false;
     for (const skill of skills) {
         const skillPath = join(root, skill.path);
         const before = await readFile(skillPath, "utf8").catch(() => null);
         if (before !== skill.source) {
             await mkdir(dirname(skillPath), { recursive: true });
             await writeFile(skillPath, skill.source, "utf8");
+            skillsMoved = true;
         }
-        console.log(body(before === skill.source
+        row(before !== skill.source, before === skill.source
             ? `· ${skill.label.padEnd(22)} already current`
             : before == null
                 ? `✓ ${skill.label.padEnd(22)} ${skill.what}`
-                : `✓ ${skill.label.padEnd(22)} updated to this CLI's pipeline`));
+                : `✓ ${skill.label.padEnd(22)} updated to this CLI's pipeline`);
     }
+    /** A tela sai agora, junta: o que mudou por nome, e o silêncio numa linha. */
+    flush();
     /**
      * O CI: escrito quando pedido, e NÃO MAIS OFERECIDO aqui.
      *
@@ -419,9 +475,29 @@ export async function connect(opts) {
     const mcpMoved = Boolean(want.mcp &&
         Array.isArray(wired.mcp) &&
         wired.mcp.some((m) => moved(m.status)));
+    /**
+     * O QUE ESTA RODADA MOVEU, PELO NOME - e são os nomes que a pessoa acabou de ler nas linhas com
+     * `✓`, não os nossos nomes internos. Uma razão que ela pode conferir contra a própria tela.
+     */
+    const bothChecks = moved(wired.hook) && moved(wired.session);
+    const loads = [
+        /** Os dois checks juntos viram "the checks": nomeá-los separados custava uma linha inteira da
+         *  tela para uma distinção que não muda nada do que a pessoa faz em seguida. */
+        ...(bothChecks
+            ? ["the checks"]
+            : moved(wired.hook)
+                ? ["the write check"]
+                : moved(wired.session)
+                    ? ["the session check"]
+                    : []),
+        ...(mcpMoved ? ["the tools"] : []),
+        ...(skillsMoved ? ["the skills"] : []),
+    ];
     await reportWhatIsLeft(root, {
         cli: opts.version,
-        ...(needsRestart ? { freshSession: { mcp: mcpMoved } } : {}),
+        ...(needsRestart || skillsMoved
+            ? { freshSession: { loads, mcp: mcpMoved } }
+            : {}),
     });
     /**
      * O CUSTO DO HOOK, DITO SEM UM NÚMERO QUE NÃO É NOSSO.
@@ -437,11 +513,20 @@ export async function connect(opts) {
      * que se sustenta.
      */
     if (wired.command.startsWith("npx synthesisui@")) {
+        /**
+         * O CUSTO DO HOOK, EM UMA LINHA - eram cinco, e elas fechavam a tela.
+         *
+         * Medido em 03/09: a tela do `connect` tinha 41 linhas, e este parágrafo era 5 delas, na última
+         * posição, falando de resolução de pacote npm. Para quem acabou de instalar, é o assunto mais
+         * distante do design system dele possível, no momento em que ele deveria estar abrindo o agente.
+         *
+         * A METADE QUE FICA É A ACIONÁVEL. O diagnóstico completo - por que o npx custa, o que foi
+         * medido, quanto o caminho local ganhou - vive na documentação do comando, guardado por
+         * `apps/web/src/lib/cli/commands.spec.ts`.
+         */
         console.log("");
-        console.log(body(paint.dim("The hook runs through npx, which resolves this package against the")));
-        console.log(body(paint.dim("registry on every edit - that wait is the network, not the check itself")));
-        console.log(body(paint.dim("(the analysis is about 80ms). Adding synthesisui to your devDependencies")));
-        console.log(body(paint.dim("makes npx resolve it locally instead, which is several times faster;")));
-        console.log(body(paint.dim("run this again afterwards and it will switch by itself.")));
+        console.log(bodyWrapped("The hook resolves against the npm registry on each edit - that is the wait, not the check. Add synthesisui to your devDependencies and run this again; it switches by itself to local, several times faster.")
+            .map(paint.dim)
+            .join("\n"));
     }
 }

package/dist/install-marks.js

@@ -152,7 +152,17 @@
  * comentou vinha sendo escrito na pasta dele como componente de verdade. Medido em 14 arquivos
  * das duas populações o nó fantasma era a RAIZ - o elemento cujas classes viram a `base`.
  */
-export const MATERIALISER_SINCE = "0.16.349";
+/**
+ * 0.16.349 -> 0.16.360 em 03/09: a casa do bloco de governança passa a NASCER da pasta da
+ * ferramenta. Um repositório com `.codex/` recebe `AGENTS.md`, e um com `.cursor/` recebe
+ * `.cursor/rules/synthesisui.mdc` - dois arquivos que o materializador antes só atualizava se a
+ * pessoa já os tivesse escrito à mão. São bytes NOVOS na pasta dele, então esta é a primeira vez em
+ * seis cobranças que o passo 1 dá SIM.
+ *
+ * O que o cliente ganha ao rodar `upgrade`: as regras do sistema passam a existir no arquivo que o
+ * agente DELE lê, em vez de só no do Claude Code.
+ */
+export const MATERIALISER_SINCE = "0.16.360";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/skills.js

@@ -36,7 +36,7 @@ export const SKILLS = [
         path: ADAPT_SKILL_PATH,
         source: ADAPT_SKILL,
         label: "/sui-adapt",
-        what: "one component against the system, and what to do about it",
+        what: "one component against the system",
     },
     /**
      * A DE CONSTRUÇÃO, e ela é a que responde ao pedido mais comum de todos:
@@ -52,7 +52,7 @@ export const SKILLS = [
         path: COMPOSE_SKILL_PATH,
         source: COMPOSE_SKILL,
         label: "/sui-compose",
-        what: "build what the system does not have, layer by layer",
+        what: "build what the system does not have",
     },
     /**
      * A DE LIGAR O SISTEMA NO APP, e ela é a única aqui que fecha um passo que a esteira já sabia
@@ -67,6 +67,6 @@ export const SKILLS = [
         path: CONFIGURE_SKILL_PATH,
         source: CONFIGURE_SKILL,
         label: "/sui-configure-ds",
-        what: "the system wired into the app, so the tokens reach the browser",
+        what: "the tokens, wired into your app",
     },
 ];

package/package.json

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