synthesisui 0.16.261 → 0.16.264

package/dist/claude-md.js

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { hasHook } from "./agent-wiring.js";
 import { declaredReference } from "./group-role.js";
+import { recallAvailable } from "./memory/availability.js";
 const START = "<!-- synthesisui:start -->";
 const END = "<!-- synthesisui:end -->";
 /** Reads the installed DSs from the .lock files in _synthesisui/ds/<slug>/. */
@@ -61,7 +62,9 @@ function catalogNames(recipes) {
  * HAS - "use these before creating new ones" - instead of re-inventing
  * buttons. Returns null when the document isn't readable (older installs).
  */
-async function readManifest(projectRoot, ds) {
+async function readManifest(projectRoot, ds, 
+/** Ver `recallAvailable`: com o servidor registrado, o índice vira mapa em vez de lista. */
+recall) {
     try {
         const raw = await readFile(join(projectRoot, "_synthesisui", "ds", ds.slug, `v${ds.version}`, "design-system.json"), "utf8");
         const doc = JSON.parse(raw);
@@ -71,14 +74,29 @@ async function readManifest(projectRoot, ds) {
             return null;
         const lines = [];
         if (components.length > 0) {
-            lines.push(`  Components (${components.length}) - look here BEFORE writing anything new:`);
+            /**
+             * A LEGENDA MUDA COM A CAPACIDADE, e os NOMES nunca.
+             *
+             * Com `recall` ao alcance, o índice deixa de ser "a lista do que existe" e passa a ser o mapa de
+             * onde perguntar - é essa a diferença entre carregar conhecimento e ensinar a encontrá-lo. Os
+             * nomes saem da MESMA fonte canônica nos dois casos (`design-system.json`), na mesma ordem, sem
+             * um item a mais nem a menos: o F0 troca uma frase, não o inventário.
+             */
+            lines.push(recall
+                ? `  Components (${components.length}) - the index; each name has knowledge you can retrieve:`
+                : `  Components (${components.length}) - look here BEFORE writing anything new:`);
             lines.push(`  ${components.map((n) => `ds-${n}`).join(" ")}`);
         }
         if (blocks.length > 0) {
             lines.push(`  Engagement blocks (${blocks.length}):`);
             lines.push(`  ${blocks.map((n) => `ds-${n}`).join(" ")}`);
         }
-        lines.push("  What each one does, its variants and states: the GUIDE above.");
+        /**
+         * E A LINHA QUE MANDAVA LER O GUIA SAI quando há como perguntar. Ela custava 24.647 bytes de
+         * leitura no sistema medido - a mesma informação que `describe_component` serve por componente.
+         */
+        if (!recall)
+            lines.push("  What each one does, its variants and states: the GUIDE above.");
         return lines.join("\n");
     }
     catch {
@@ -297,6 +315,14 @@ async function renderRegion(projectRoot, installed) {
     if (installed.length === 0) {
         return `${START}\n${END}`;
     }
+    /**
+     * A CAPACIDADE, MEDIDA UMA VEZ POR ARQUIVO - ver `recallAvailable`.
+     *
+     * Não é "qual agente é este": é "este repositório tem o servidor registrado, numa versão que serve
+     * `recall`?". Os dois editores gravam o mesmo shape em caminhos diferentes, então a checagem vale
+     * para qualquer agente que leia esse formato - inclusive um que ainda não existe.
+     */
+    const recall = await recallAvailable(projectRoot);
     const sections = [];
     for (const ds of installed) {
         // An adopted system has no published version and therefore no `v<n>/`
@@ -305,7 +331,7 @@ async function renderRegion(projectRoot, installed) {
         const head = ds.adopted
             ? `- **${ds.name}** (\`${ds.slug}\`, adopted from this repo) - guide: \`_synthesisui/ds/${ds.slug}/GUIDE.md\``
             : `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``;
-        const manifest = await readManifest(projectRoot, ds);
+        const manifest = await readManifest(projectRoot, ds, recall.available);
         sections.push(manifest ? `${head}\n${manifest}` : head);
     }
     // Two truths, and asserting the wrong one misleads the agent every time it
@@ -332,16 +358,97 @@ async function renderRegion(projectRoot, installed) {
         sections.push(`\n**${ref.name}** (\`${ref.slug}\`) is the reference system of this group. When two of the systems above name the same thing differently, its answer is the one to follow - the others are moving towards it.`);
     }
     const onlyAdopted = installed.every((d) => d.adopted);
-    const selfCheck = (await hasHook(projectRoot))
-        ? SELF_CHECK_HOOKED
-        : SELF_CHECK_MANUAL;
-    const rule = onlyAdopted
-        ? `**When creating or editing components, read the system's GUIDE.md and follow it:** use the
+    /**
+     * O PORTÃO LOCAL OBRIGATÓRIO, EM DUAS LINHAS quando há como buscar o resto.
+     *
+     * O texto longo explica três ferramentas - o `doctor --verbose`, o `request_token` e o
+     * `refresh_system` -, com a justificativa de cada uma. Justificativa é conhecimento recuperável:
+     * ela mora no `doctor` e no playbook, que é onde a pessoa e o agente estão quando ela importa.
+     *
+     * O que NÃO é recuperável e por isso fica: que existe um portão, que ele roda por arquivo tocado, e
+     * que um valor sem token não se inventa. É gate obrigatório, não documentação.
+     */
+    const selfCheck = recall.available
+        ? `
+
+**Check what you wrote** with \`check_file\` on the file you touched, and fix what it names before
+moving on. If it names a value this system has no token for, do not invent one - file it the same way
+you would file a missing component. And call \`refresh_system\` once per session before writing UI
+here: a newer reader sees styles the old one could not.`
+        : (await hasHook(projectRoot))
+            ? SELF_CHECK_HOOKED
+            : SELF_CHECK_MANUAL;
+    /**
+     * O BOOTSTRAP É REDUZIDO QUANDO EXISTE CAMINHO DE VOLTA - e o portão é CAPACIDADE, não nome.
+     *
+     *     Bootstrap contains invariants, discovery, and mandatory local gates;
+     *     retrievable knowledge stays outside the bootstrap.
+     *
+     * Sem servidor MCP registrado, o texto longo continua inteiro: cortar a instrução de ler o guia
+     * onde não há ferramenta para perguntar trocaria contexto por ignorância. `add` escreve este
+     * arquivo e `connect` registra o servidor - são dois comandos, então a garantia não vem por
+     * construção e tem que ser medida.
+     *
+     * O que SAI daqui: "read the system's GUIDE.md and follow it" (24.647 bytes no sistema medido) e a
+     * linha que mandava o guia explicar cada componente. O que FICA: as invariantes que ninguém
+     * descobre sozinho, o índice, a materialização, os nomes das três ferramentas de descoberta com uma
+     * linha cada, o `recall` por assunto, e o portão local obrigatório (`check_file`).
+     *
+     * A instrução de `connect` NÃO entra na versão reduzida: o mesmo `wireAgent` que registra o
+     * servidor instala o hook, e o registro é pré-condição para este texto existir. Ensinar a instalar
+     * uma capacidade que foi pré-requisito do próprio arquivo é redundância por construção.
+     */
+    const rule = recall.available
+        ? onlyAdopted
+            ? `**These are true without asking anyone:** use the project's OWN custom properties, exactly as
+this system declares them. No raw colours, spacings or radii that a token already covers, and never a
+new token invented in silence - say so instead, because a new token is a decision for a person. There
+is no component index for an adopted system: the tokens ARE the contract.
+
+**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.
+
+**What this project already DECIDED is \`recall\`.** Call it when you begin work on a subject this
+system names, or when someone says "continue" and you need the current work-state. For the same
+subject and task, call it once - an empty result means there is nothing more to retrieve, so keep
+working. It 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.${selfCheck}`
+            : `**These are true without asking anyone:**
+
+- Semantic tokens only - \`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`. No raw values outside this
+  system's scale.
+- Scope the UI with \`data-ds="<slug>"\` and reuse the \`.ds-*\` classes.
+- To override a style a component already sets, use this system's semantic role class - never \`!\`.
+  If the override is ignored, regenerate that component: older ones predate the resolver.
+- Motion is selection, not improvisation. The base is quiet: nothing moves until a person asks, and
+  what moves comes from this system's own vocabulary - never hand-rolled \`@keyframes\` or raw durations.
+
+**When you are writing UI that belongs to one of the systems below, check its index first.** If an
+entry covers the purpose, do not write it from scratch - materialise it:
+
+    npx synthesisui@latest component <slug> <name>
+
+If nothing covers it, say which indexed entry you considered and why it did not fit, then file a
+\`request_component\` while the reasoning is still fresh. A refusal said only in chat evaporates.
+
+**What an entry IS is not written here.** Fetch only the piece the task requires:
+
+    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
+
+**What this project already DECIDED is \`recall\`.** Call it when you begin work on an indexed
+subject, or when someone says "continue" and you need the current work-state. For the same subject
+and task, call it once - an empty result means there is nothing more to retrieve, so keep working. It
+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.${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,
 spacings or radii that a token already covers, and do not invent a new token silently - say so
 instead, because a new token is a decision for a person to make. There is no component
 manifest for an adopted system - the tokens ARE the contract.${selfCheck}`
-        : `**When creating or editing components, read the system's GUIDE.md and follow it:** use only semantic tokens
+            : `**When creating or editing components, read the system's GUIDE.md and follow it:** use only semantic tokens
 (\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), scope the UI with \`data-ds="<slug>"\`,
 and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale.
 

package/dist/commands/import.js

@@ -4,7 +4,7 @@ import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
-import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
+import { architectureRule, componentHome, describeArchitecture, describeChoice, detectArchitectures, homeLine, proposeNewHome, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, readRuntime, } from "../doctor/call-sites.js";
 import { asCatalogueTable, describeFallback, fetchCatalogue, } from "../doctor/catalogue-fetch.js";
@@ -37,6 +37,7 @@ import { frontierKind, packageRoot } from "../frontier-kind.js";
 import { withLibraryStructure } from "../library-structure.js";
 import { mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
+import { namingQueue } from "../naming-queue.js";
 import { body, paint, section } from "../output.js";
 import { phase, startProgress } from "../progress.js";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
@@ -1928,6 +1929,18 @@ export async function takeCensus(root, opts) {
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
     const classStyle = detectClassStyle(sources);
+    /**
+     * A FILA DE NOMES, computada com os MESMOS insumos que o envio usa - ver `namingQueue`.
+     *
+     * O crosswalk e o manifesto entram porque é o que distingue um componente DELES de uma peça de
+     * terceiro, e os dois casos são nós já nomeados. Sem eles a fila cobraria trabalho que não
+     * existe, que é exatamente o defeito que ela vem medir.
+     */
+    const naming = namingQueue(looks, (name) => {
+        const c = components.find((x) => x.name === name && !x.from);
+        const target = c?.canonical ?? (c?.bucket === "exclusive" ? c.name : null);
+        return target ? safePartName(target) : null;
+    }, (pkg) => versions[pkg]);
     return {
         census: 1,
         project: {
@@ -1964,6 +1977,7 @@ export async function takeCensus(root, opts) {
         ...(conventions.length > 0 ? { conventions } : {}),
         classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
+        ...(naming.components > 0 ? { naming } : {}),
         ...(schemes.alt.size > 0
             ? { declaredAlt: Object.fromEntries(schemes.alt) }
             : {}),
@@ -2026,8 +2040,16 @@ export async function takeCensus(root, opts) {
             ? {
                 architectures: architectures.slice(0, 6).map((a) => ({
                     ...a,
-                    rule: architectureRule(a),
+                    /** O caminho e a frase que a PERGUNTA usa verbatim - ver `componentHome`. */
+                    home: componentHome(a, scopeLabel),
+                    line: homeLine(a),
+                    rule: architectureRule(a, scopeLabel),
                 })),
+                ...(proposeNewHome(architectures, scopeLabel)
+                    ? {
+                        newComponentHome: proposeNewHome(architectures, scopeLabel),
+                    }
+                    : {}),
             }
             : {}),
         ...(skips.length > 0
@@ -3570,7 +3592,11 @@ export async function runImport(opts) {
             "content-type": "application/json",
             Authorization: `Bearer ${token}`,
         },
-        body: JSON.stringify({ census, name: chosen }),
+        body: JSON.stringify({
+            census,
+            name: chosen,
+            ...(opts.group ? { group: opts.group } : {}),
+        }),
     }).catch(() => null);
     if (!res || !res.ok) {
         const detail = res
@@ -3602,6 +3628,15 @@ export async function runImport(opts) {
     console.log("");
     console.log(section("Your system exists"));
     console.log(body(`${paint.strong(payload?.name ?? "Your system")} - v1 mirrors your tokens exactly, nothing improved yet.`));
+    /**
+     * ONDE ELE NASCEU, dito pela plataforma e não pelo que foi pedido.
+     *
+     * A flag carrega um nome falado e o casamento acontece do outro lado, então imprimir o que foi
+     * pedido provaria nada. Este é o campo que o dono não teve em 20/08, quando dois sistemas
+     * nasceram no espaço pessoal dele e o grupo ficou vazio.
+     */
+    if (payload?.group)
+        console.log(body(paint.dim(`In the group ${payload.group}.`)));
     for (const note of payload?.notes ?? [])
         console.log(body(paint.dim(note)));
     // What a v2 would be worth, in their own values. Said here because this is

package/dist/commands/mcp.js

@@ -9,6 +9,7 @@ import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
+import { MEMORY_TOOLS } from "../memory/tools.js";
 import { repoStateOf } from "../repo-state.js";
 import { component } from "./component.js";
 import { loadSystem, walkAll } from "./doctor.js";
@@ -272,6 +273,14 @@ const TOOLS = [
             required: ["name", "purpose"],
         },
     },
+    /**
+     * A MEMÓRIA - o que este projeto já decidiu, e o que alguém está fazendo agora.
+     *
+     * Duas ferramentas estreitas em vez de uma genérica: quanto menos combinatória o schema oferece,
+     * menos estado impossível existe para validar depois. Os dois schemas são fechados e NENHUM campo
+     * derivado aparece neles - `memory/tools.spec.ts` percorre os dois e reprova se um vazar.
+     */
+    ...MEMORY_TOOLS,
 ];
 /**
  * QUANTAS FERRAMENTAS ESTE SERVIDOR SERVE, lido da lista.

package/dist/commands/sync.js

@@ -6,6 +6,8 @@ import { markSent, readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { describeDelta, fingerprintReadings, readSyncMark, writeSyncMark, } from "../last-sync.js";
 import { measuredScope, rememberScope } from "../measured-scope.js";
+import { fromCensus } from "../memory/observation.js";
+import { reportMeasurement } from "../memory/report.js";
 import { mergeCensus } from "../merge-census.js";
 import { body, paint, section, snippet } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
@@ -506,6 +508,77 @@ export async function remeasure(args) {
     };
     console.log(body(paint.faint(describeDelta(mark, await readSyncMark(root)))));
     await writeSyncMark(root, mark);
+    /**
+     * O CANAL DE MEDIÇÃO - o `sync` testemunha o que a plataforma não pode observar.
+     *
+     * Ela guarda os trabalhos declarados ("estamos migrando o Checkout para o novo Button"); o
+     * repositório está aqui. Então este comando pergunta o que está aberto, mede tudo com um snapshot
+     * só, e devolve os veredictos - e é por isso que o trabalho fecha sozinho quando a realidade o
+     * fecha, em vez de esperar alguém lembrar.
+     *
+     * DEGRADAÇÃO SEGURA, e ela não é acidental: uma plataforma que ainda não tem a rota - o intervalo
+     * normal entre publicar no npm e fazer deploy - responde 404, o `open()` devolve nada, e o `sync`
+     * segue exatamente como antes. Um repositório sem trabalho declarado também não paga nada.
+     */
+    const work = await reportMeasurement({
+        at: new Date().toISOString(),
+        ...(args.cli ? { cli: args.cli } : {}),
+        ...(scope ? { scope } : {}),
+        obs: fromCensus(census),
+        open: async () => {
+            /**
+             * SEM REDE NÃO É "FEATURE AUSENTE", e a diferença é fina mas importa (dono, 20/08).
+             *
+             * Aqui ela fica precisa por um detalhe deste comando: o `sync` já falou com a plataforma no
+             * começo - ele buscou a leitura guardada e teria parado se não tivesse resposta. Então uma
+             * exceção de rede NESTE ponto é anômala, não é o modo offline: a plataforma respondia trinta
+             * segundos atrás. Ela vira aviso, e um 404 continua sendo silêncio de compatibilidade.
+             */
+            let res = null;
+            try {
+                res = await fetch(`${base}/api/memory/${slug}/open`, {
+                    headers: { Authorization: `Bearer ${token}` },
+                });
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    reason: "error",
+                    detail: `network: ${e instanceof Error ? e.message : String(e)}`,
+                };
+            }
+            /** 404 é a rota que ainda não subiu - o intervalo entre publicar no npm e fazer deploy. */
+            if (res.status === 404)
+                return { ok: false, reason: "not-installed" };
+            if (!res.ok)
+                return {
+                    ok: false,
+                    reason: "error",
+                    status: res.status,
+                };
+            const payload = (await res.json().catch(() => null));
+            return { ok: true, open: payload?.open ?? [] };
+        },
+        send: async (payload) => {
+            await fetch(`${base}/api/memory/${slug}/measured`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(payload),
+            });
+        },
+    }).catch((e) => ({
+        measured: 0,
+        skipped: null,
+        failed: { detail: e instanceof Error ? e.message : String(e) },
+    }));
+    /** UM DEFEITO DE MEDIÇÃO NÃO PODE SER SILÊNCIO - é a diferença entre 404 e o resto. */
+    if ("failed" in work && work.failed)
+        console.log(body(paint.faint(`⚠ declared work could not be re-checked${work.failed.status ? ` (HTTP ${work.failed.status})` : work.failed.detail ? ` (${work.failed.detail})` : ""} - your measurement was sent, this part was not`)));
+    if (work.measured > 0)
+        console.log(body(paint.faint(`${work.measured} declared piece${work.measured === 1 ? "" : "s"} of work re-checked against this measurement`)));
     if (!args.full)
         console.log(body(paint.faint("everything the reader saw:  npx synthesisui sync --full")));
 }

package/dist/doctor/architecture.js

@@ -106,15 +106,77 @@ export function describeArchitecture(a) {
  * open one component. And `fact: true`, because it was read off their directories: it is
  * true once, not a habit that needs a third sighting.
  */
-export function architectureRule(a) {
+export function architectureRule(a, 
+/**
+ * O ESCOPO, para a regra dizer um caminho que existe. `a.root` é relativo ao escopo, e uma
+ * regra no CLAUDE.md de um monorepo que diz `src/lib/SignalUI` manda o agente para um caminho
+ * que não resolve da raiz - o mesmo defeito que fez o dono reprovar as opções da pergunta.
+ */
+scope) {
+    const home = componentHome(a, scope);
     return {
-        text: describeArchitecture(a),
+        text: `${describeArchitecture(a)} A new component goes under \`${home}\`.`,
         applies: [],
         kind: "implementation",
         fact: true,
-        evidence: `${a.evidence.join("/")} under ${a.root}, holding ${a.files} component file${a.files === 1 ? "" : "s"}`,
+        evidence: `${a.evidence.join("/")} under ${scope ? `${scope}/${a.root}` : a.root}, holding ${a.files} component file${a.files === 1 ? "" : "s"}`,
     };
 }
+/**
+ * ONDE UM COMPONENTE NOVO VAI, ESCRITO COMO CAMINHO - e o caminho é a resposta.
+ *
+ * O dono leu esta pergunta na tela em 20/08 e a reprovou por uma razão que a versão
+ * anterior não tinha como resolver: *"'manter a escada atômica' não responde onde nasce
+ * o componente"*. O título de cada opção era o NOME DO PADRÃO e a árvore estava enterrada
+ * numa descrição de quatro linhas - então a pergunta pedia uma decisão de organização e
+ * mostrava um glossário.
+ *
+ * A resposta a "onde" é um caminho. Então o caminho é o título, ele vem daqui pronto, e
+ * ele é COMPLETO a partir da raiz do repositório: `src/lib/SignalUI` sem o `packages/ui/`
+ * na frente é ambíguo num monorepo, e é para o CLAUDE.md que essa linha vai.
+ */
+export function componentHome(a, scope) {
+    const base = scope ? `${scope.replace(/\/+$/, "")}/${a.root}` : a.root;
+    const tidy = base.replace(/\/\.$/, "").replace(/^\.\//, "");
+    return a.evidence.length > 0 ? `${tidy}/{${a.evidence.join(", ")}}` : tidy;
+}
+/**
+ * A MESMA FORMA EM UMA FRASE - o que decide, e o número que a torna credível.
+ *
+ * `describeArchitecture` continua existindo e continua longo: ele é a REGRA que vai para
+ * o CLAUDE.md, onde um agente precisa do critério inteiro. Numa lista de opções esse
+ * mesmo texto é o que faz três linhas viraram doze e ninguém ler nenhuma.
+ */
+const LINES = {
+    atomic: (a) => `A rung per what it composes - atom, molecule, organism. ${a.files} files already here.`,
+    feature: (a) => `Beside the feature that uses it; it moves up only when a second one needs it. ${a.files} files.`,
+    layered: (a) => `By layer - ui, hooks, utils - not by feature. ${a.files} files already here.`,
+    flat: (a) => `One folder deep, no ladder. Legible while the system is small. ${a.files} files.`,
+    colocated: (a) => `Beside the route that renders it, shared only when a second page needs it. ${a.files} files.`,
+};
+export function homeLine(a) {
+    return LINES[a.kind](a);
+}
+/**
+ * UMA PASTA NOVA, PROPOSTA - a opção que faltava, e o dono pediu por ela.
+ *
+ * As opções eram todas retratos: manter isto, manter aquilo. Nenhuma deixava alguém dizer
+ * *"daqui em diante vai num lugar novo"*, que é uma resposta legítima e frequente - e sem
+ * ela a pergunta é sobre o passado.
+ *
+ * O caminho é DERIVADO, não inventado: fica dentro do escopo que a pessoa já apontou como
+ * fonte de verdade, e usa `src/` só quando as formas medidas mostram que o escopo tem `src`.
+ * Sem nome de sistema dentro dele de propósito - quem quer isso digita, e digitar um nome
+ * é mais honesto do que a gente adivinhar a grafia dele.
+ */
+export function proposeNewHome(found, scope) {
+    const base = scope ? scope.replace(/\/+$/, "") : "";
+    const hasSrc = found.some((a) => a.root === "src" || a.root.startsWith("src/"));
+    const trunk = `${base ? `${base}/` : ""}${hasSrc ? "src/components" : "components"}`;
+    const fresh = `${trunk}/{atoms, molecules, organisms}`;
+    /** Se a proposta é o que já existe, ela não é uma pasta nova - e oferecê-la seria repetir a opção 1. */
+    return found.some((a) => componentHome(a, scope) === fresh) ? null : fresh;
+}
 /**
  * A ESTRUTURA, ESCRITA - as pastas que a forma tem, na ordem em que ela as usa.
  *

package/dist/index.js

@@ -88,7 +88,11 @@ Options:
   --dir <path>       consumer project root (default: current directory)
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
-  --name <name>      preferred component name for generate
+  --name <name>      import: the NAME of the system, which is what its install slug
+                     comes from - and the slug never changes. Also the preferred
+                     component name for generate.
+  --group <name>     import: the GROUP it is born in, by name ("--group SignalUI").
+                     Without it the system lands in your own space.
   --scope <path>     import: the SYSTEM - tokens, components, convention. Repeatable;
                      the first one wins a tie.
   --usage <path>     import: the EVIDENCE - counts, chosen values, laws. Repeatable.
@@ -158,6 +162,14 @@ async function main() {
                 dry: flags.dry === true,
                 census: typeof flags.census === "string" ? flags.census : undefined,
                 name: typeof flags.name === "string" ? flags.name : undefined,
+                /**
+                 * EM QUAL GRUPO ELE NASCE - o nome, como a pessoa o fala.
+                 *
+                 * Sem a flag, no espaço pessoal (o padrão de sempre). Com ela, no grupo que ela nomeou -
+                 * e um nome que a plataforma não reconhece RECUSA o envio em vez de cair no pessoal, que
+                 * é o desvio que ninguém percebe até ir procurar o sistema.
+                 */
+                group: typeof flags.group === "string" ? flags.group : undefined,
                 // Only these two words. Anything else is a typo that would silently
                 // invert a system, so it falls through to being measured and asked.
                 // WHAT to read. `--dir` stays WHERE the project is, in every command.

package/dist/install-marks.js

@@ -100,7 +100,22 @@
  *
  * Quem instalou antes desta versão tem o stub que estanca: o `upgrade`/`connect` é o que alcança.
  */
-export const MATERIALISER_SINCE = "0.16.259";
+/**
+ * `0.16.259` -> `0.16.264` em 20/08, e esta é a primeira vez nesta sessão que a marca SOBE.
+ *
+ * O F0: onde o servidor MCP está registrado, o bloco gerenciado do `CLAUDE.md` deixa de mandar ler o
+ * `GUIDE.md` inteiro e passa a apontar as ferramentas que servem a peça. Medido no sistema real:
+ * 6.815 -> 2.936 bytes de bootstrap, e a leitura de 24.647 bytes que a instrução provocava deixa de
+ * acontecer.
+ *
+ * UM CLIENTE PINADO RECEBE ALGO DIFERENTE NA PASTA? SIM - o texto que o agente dele lê antes de
+ * escrever qualquer UI é outro. É exatamente o que esta marca existe para dizer, e é por isso que ela
+ * anda: quem está atrás vê a versão antiga do manifesto até rodar `upgrade`.
+ *
+ * O índice de componentes é BYTE-IDÊNTICO nos dois caminhos - mesma fonte canônica, mesmos nomes,
+ * mesma quantidade (`claude-md.f0.spec.ts`). O corte troca uma frase, nunca o inventário.
+ */
+export const MATERIALISER_SINCE = "0.16.264";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/memory/availability.js

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * O RECALL ESTÁ AO ALCANCE DESTE REPOSITÓRIO? - e é isto que decide o tamanho do `CLAUDE.md`.
+ *
+ * O corte do manifesto só é honesto onde existe caminho de volta. E ele NÃO é garantido por
+ * construção: `add` escreve o `CLAUDE.md`, `connect` registra o servidor MCP, e são dois comandos.
+ * Alguém que rodou `add` sem `connect` receberia um manifesto enxuto e nenhuma ferramenta para buscar
+ * o que saiu dele - trocaria contexto por ignorância.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * CAPACIDADE, NUNCA NOME DE AGENTE
+ *
+ * A pergunta não é "isto é Claude Code ou Cursor". É "este repositório tem o servidor registrado, numa
+ * versão que serve `recall`?". Os dois editores gravam o MESMO shape (`mcpServers`) em caminhos
+ * diferentes, então a checagem é uma só e vale para qualquer agente que leia esse formato - inclusive
+ * um que ainda não existe.
+ *
+ * E ela não inventa configuração: o sinal é o registro que o `connect` já escreve.
+ */
+/** Onde os agentes leem o servidor - o mesmo shape, dois caminhos. */
+const MCP_FILES = [".mcp.json", ".cursor/mcp.json"];
+/** A versão em que `recall` e `remember` passaram a existir. */
+export const RECALL_SINCE = "0.16.264";
+const older = (mine, than) => {
+    const parts = (v) => v.split(".").map((p) => Number.parseInt(p, 10));
+    const a = parts(mine);
+    const b = parts(than);
+    for (let i = 0; i < 3; i += 1) {
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return false;
+    }
+    return false;
+};
+export async function recallAvailable(root) {
+    for (const rel of MCP_FILES) {
+        const raw = await readFile(join(root, rel), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        const parsed = JSON.parse(raw);
+        const entry = parsed?.mcpServers?.synthesisui;
+        if (!entry)
+            continue;
+        /**
+         * UMA ENTRADA PINADA NUMA VERSÃO ANTIGA NÃO SERVE `recall`.
+         *
+         * Quem conectou antes de 06/08 ficou com o servidor pinado, e o `connect` só solta isso quando
+         * roda de novo. Um manifesto enxuto sobre um servidor de duas semanas atrás manda o agente chamar
+         * uma ferramenta que não existe naquele processo.
+         */
+        const pin = (entry.args ?? [])
+            .map(String)
+            .map((a) => /^synthesisui@(\d[\d.]*)$/.exec(a)?.[1])
+            .find(Boolean);
+        if (pin && older(pin, RECALL_SINCE))
+            return {
+                available: false,
+                because: `the MCP server in ${rel} is pinned to ${pin}, older than ${RECALL_SINCE} - run \`synthesisui connect\` to let it float`,
+            };
+        return {
+            available: true,
+            because: `the MCP server is registered in ${rel}`,
+        };
+    }
+    return {
+        available: false,
+        because: "no MCP server is registered in this repository - run `synthesisui connect` so the agent can look memory up",
+    };
+}