synthesisui 0.16.263 → 0.16.265

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,111 @@ 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.
+     */
+    /**
+     * O RECALL SÓ É PROMETIDO ONDE ELE TEM ONDE CHEGAR - e este era um GAP de jornada.
+     *
+     * `recallAvailable` responde "o servidor MCP está registrado numa versão que serve `recall`", e essa
+     * é a pergunta certa sobre CAPACIDADE. Ela não é a pergunta sobre ALCANCE: `memoryReach` no servidor
+     * exige `installedSlug`, que ignora locks `adopted` porque um sistema adotado é lido do repositório e
+     * não tem linha de dashboard para a memória pertencer.
+     *
+     * Sem esta condição, um projeto só-adotado recebia um bootstrap dizendo *"what this project already
+     * DECIDED is `recall`"* e toda chamada respondia "no system installed here that belongs to a
+     * dashboard row" - o bootstrap prometendo uma ferramenta que não podia funcionar ali. As outras do
+     * bloco reduzido continuam valendo, porque `system_doctrine` e `find_token` leem arquivo local.
+     *
+     * Achado seguindo a jornada, não lendo o módulo: os dois lados estavam certos sobre a própria
+     * pergunta e ninguém comparava as duas.
+     */
+    const memoryReachable = recall.available && !onlyAdopted;
+    const memoryLine = memoryReachable
+        ? `
+
+**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.`
+        : "";
+    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.${memoryLine}${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${memoryLine}${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/connect.js

@@ -11,6 +11,7 @@ import { add } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
 import { ci } from "./ci.js";
 import { MCP_TOOL_COUNT } from "./mcp.js";
+import { installedSlugs } from "./sync.js";
 /**
  * `synthesisui connect` - put the three layers where they actually run.
  *
@@ -213,6 +214,21 @@ export async function connect(opts) {
     // after them, not before.
     const contract = await syncClaudeMd(root);
     console.log(section("Connected"));
+    /**
+     * E O QUE FALTA, DITO EM VOZ ALTA - porque este comando estava mentindo por omissão.
+     *
+     * `connect` liga a conta e registra o servidor MCP. Ele NÃO instala sistema, e sem lock o bloco
+     * gerenciado do `CLAUDE.md` sai VAZIO: o agente não recebe índice, não recebe invariante, e as duas
+     * ferramentas de memória recusam com "no system installed here". A saída dizia apenas "Connected",
+     * que é verdade e é inútil.
+     *
+     * Custou tempo de gente de verdade: 20/08, `codelevel-monorepo`. Rodou `connect`, conferiu o
+     * `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.
+     */
+    const anyInstalled = (await installedSlugs(root).catch(() => [])).length > 0;
+    if (!anyInstalled)
+        console.log(body("· no design system installed here yet - `synthesisui list` shows yours, and `synthesisui add <slug>` brings one in. Until then the agent has no index and memory has nothing to belong to."));
     /**
      * 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

package/dist/commands/mcp.js

@@ -9,7 +9,10 @@ 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 { fromCensus } from "../memory/observation.js";
+import { handleRecall, handleRemember, MEMORY_TOOLS } from "../memory/tools.js";
 import { repoStateOf } from "../repo-state.js";
+import { detectStack } from "../stack.js";
 import { component } from "./component.js";
 import { loadSystem, walkAll } from "./doctor.js";
 import { installedSlug, remeasure } from "./sync.js";
@@ -272,6 +275,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.
@@ -1238,6 +1249,39 @@ cli) {
  * procedência. Nenhuma linha dele conta nada: quem instrumenta é `callTool`,
  * uma vez, para todas.
  */
+/**
+ * O ELO QUE FALTAVA - `remember` e `recall` eram ANUNCIADOS e não despachados.
+ *
+ * As duas estavam na lista de `TOOLS` desde o primeiro dia, importadas no topo deste arquivo, com 152
+ * testes verdes atrás delas - e sem `case` no `runTool`. Um agente que as chamasse recebia
+ * `"unknown tool"` com `isError`. O `reachable.spec` não pegou porque IMPORTAR já conta como
+ * alcançável, e o próprio cabeçalho dele diz o que ele não cobre: *"nothing about whether the product
+ * calls it, and that gap is exactly where the work kept"*.
+ *
+ * Achado seguindo a jornada pelo ponto de entrada real, que é a lei 3. Um spec verde prova que a
+ * função roda; não prova que o produto a chama.
+ */
+async function memoryReach(root) {
+    const slug = await installedSlug(root);
+    if (!slug)
+        return "No system installed here that belongs to a dashboard row, so there is nothing to remember about. `synthesisui add <slug>` installs one.";
+    const token = await readToken();
+    if (!token)
+        return "Not signed in, so memory cannot be reached. A person has to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.";
+    return { slug, token, base: resolveRegistry() };
+}
+/** O censo já em disco, como Observation - o mesmo insumo que o `sync` mede. */
+async function localObservation(root) {
+    const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        return fromCensus(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
 async function runTool(root, name, args) {
     switch (name) {
         case "check_file":
@@ -1397,6 +1441,68 @@ async function runTool(root, name, args) {
                 ? `${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);
         }
+        case "remember": {
+            const reach = await memoryReach(root);
+            if (typeof reach === "string")
+                return fromContract(reach);
+            /**
+             * A OBSERVAÇÃO É EXIGIDA para work-state, e só para ele: a condição de saída tem que ser
+             * verificável contra ESTE repositório, senão a memória nasce impossível de fechar.
+             */
+            const obs = await localObservation(root);
+            if (!obs)
+                return fromContract("No `_synthesisui/census.json` here, so nothing can be checked against this repository. Run `npx synthesisui sync` first - a work state whose condition nobody can measure is memory that starts lying.");
+            return handleRemember(args, obs, async (payload) => {
+                const res = await fetch(`${reach.base}/api/memory/${reach.slug}/remember`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        Authorization: `Bearer ${reach.token}`,
+                    },
+                    body: JSON.stringify(payload),
+                }).catch(() => null);
+                if (!res)
+                    return {
+                        accepted: false,
+                        reason: "unknown_field",
+                        details: "the platform could not be reached",
+                    };
+                const said = (await res.json().catch(() => null));
+                return (said ?? {
+                    accepted: false,
+                    reason: "unknown_field",
+                    details: `the platform answered ${res.status} with nothing readable`,
+                });
+            });
+        }
+        case "recall": {
+            const reach = await memoryReach(root);
+            if (typeof reach === "string")
+                return fromContract(reach);
+            /** A stack sai do repositório, nunca do agente: ela FILTRA, e um palpite dele cortaria regra boa. */
+            const stack = await detectStack(root);
+            return handleRecall(args, stack, async (request) => {
+                const res = await fetch(`${reach.base}/api/memory/${reach.slug}/recall`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        Authorization: `Bearer ${reach.token}`,
+                    },
+                    body: JSON.stringify(request),
+                }).catch(() => null);
+                const empty = {
+                    carried: [],
+                    groups: [],
+                    omitted: [],
+                    because: res
+                        ? `the platform answered ${res.status}`
+                        : "the platform could not be reached",
+                };
+                if (!res?.ok)
+                    return empty;
+                return ((await res.json().catch(() => null)) ?? empty);
+            });
+        }
         case "request_token": {
             const name = String(args.name ?? "");
             // TRIAGE AT FILING: if the system's own contract already promises this

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/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.265";
 /**
  * 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",
+    };
+}

package/dist/memory/contract.js

@@ -0,0 +1,106 @@
+/**
+ * O CONTRATO DA MEMÓRIA - e é a ÚNICA coisa desta feature que existe nos dois lados.
+ *
+ * O CLI é publicado standalone e não pode importar os contratos da plataforma, então este arquivo é
+ * um GÊMEO BYTE-IDÊNTICO de `apps/web/src/lib/memory/contract.ts`, garantido por spec - o mesmo
+ * padrão de `frontier-kind.ts`.
+ *
+ * A REGRA QUE DECIDE O QUE ENTRA AQUI (dono, 20/08):
+ *
+ *     contrato pode ser duplicado e verificado; LÓGICA nunca.
+ *
+ * Entram tipos, enums, códigos de recusa e a metadata declarativa dos predicados. NÃO entram
+ * `evaluate`, `compareProgress`, `canonicalize`, `recall` nem qualquer função que decida algo: cada
+ * uma dessas tem um dono só, e duplicar semântica é como duas implementações começam a divergir sem
+ * ninguém perceber.
+ *
+ * E a divisão que este arquivo serve:
+ *
+ *     O CLI OBSERVA E TESTEMUNHA.   A PLATAFORMA LEMBRA E DECIDE O EFEITO DA EVIDÊNCIA.
+ */
+export const CATALOGUE = {
+    reference_replaced: {
+        needs: ["from", "to"],
+        requiresAlive: ["subject"],
+        requiresReadableStyles: false,
+    },
+    inbound_references_zero: {
+        needs: [],
+        requiresAlive: [],
+        requiresReadableStyles: false,
+        progress: { field: "remaining", direction: "decrease" },
+    },
+    reference_present: {
+        needs: ["to"],
+        requiresAlive: ["subject"],
+        requiresReadableStyles: false,
+    },
+    reference_absent: {
+        needs: ["from"],
+        requiresAlive: ["subject"],
+        requiresReadableStyles: false,
+    },
+    token_present: {
+        needs: ["to"],
+        requiresAlive: [],
+        requiresReadableStyles: true,
+    },
+    token_absent: {
+        needs: ["from"],
+        requiresAlive: [],
+        requiresReadableStyles: true,
+    },
+    component_present: {
+        needs: [],
+        requiresAlive: [],
+        requiresReadableStyles: false,
+    },
+    component_absent: {
+        needs: [],
+        requiresAlive: [],
+        requiresReadableStyles: false,
+    },
+};
+export const DECLARABLE = [
+    "developer_declared",
+    "agent_inferred",
+    "imported",
+];
+/**
+ * AS TAREFAS, LISTA FECHADA - derivada do que a plataforma JÁ MEDE.
+ *
+ * Mesma regra do catálogo: a linguagem cresce quando a capacidade de medição cresce.
+ */
+export const TASKS = [
+    "tokens",
+    "spacing",
+    "typography",
+    "contrast",
+    "accessibility",
+    "migration",
+];
+/**
+ * O QUE O AGENTE NÃO PODE PROPOR: "ele pode propor fatos, nunca a autoridade dos fatos".
+ *
+ * `verdict` e `snapshotId` entraram nesta lista quando a fronteira de medição passou a existir: um
+ * agente que pudesse enviar `verdict: "met"` se concederia a autoridade de ter medido.
+ */
+export const DERIVED_FIELDS = [
+    "owner",
+    "fingerprint",
+    "confidence",
+    "authority",
+    "rung",
+    "status",
+    "measuredAt",
+    "measured_at",
+    "lastProgressAt",
+    "lastMeasuredAt",
+    "evidenceSource",
+    "resolution",
+    "active",
+    "verdict",
+    "progress",
+    "snapshotId",
+    "snapshot_id",
+];