synthesisui 0.16.413 → 0.16.415

package/dist/agent-wiring.js

@@ -150,16 +150,18 @@ async function wireHook(root, command) {
 /**
  * O MESMO SERVIDOR MCP, NOS CAMINHOS QUE CADA AGENTE LÊ.
  *
- * `.mcp.json` é o escopo-de-projeto do Claude Code; o Cursor lê `.cursor/mcp.json` com o MESMO shape
+ * `.mcp.json` é o escopo-de-projeto do Claude Code. O Cursor lia `.cursor/mcp.json` com o mesmo shape
  * (`mcpServers`). Então cobrir os dois é o mesmo JSON num segundo caminho, e as ferramentas passam
  * a existir nos dois editores sem uma linha de motor novo - era a lacuna mais barata da análise de DX
  * (05/08).
  *
- * O SEGUNDO SÓ SE A PASTA JÁ EXISTIR. Criar `.cursor/` num repo de quem usa Claude Code é escrever
- * arquivo de um editor que a pessoa não usa, e é a primeira coisa que alguém apaga com raiva - a
- * mesma regra que já vale para o `AGENTS.md`.
+ * O CURSOR SAIU EM 10/09, por decisão dele: a lista do produto é Claude Code e Codex (ver
+ * `agents-chosen.ts` e `cursor-is-retired.spec.ts`). O que sobreviveu daquela linha é a regra que
+ * ela ensinou - escrever arquivo de um editor que a pessoa não usa é a primeira coisa que alguém
+ * apaga com raiva -, e ela agora vale para TODOS, inclusive o Claude Code: quem decide é a escolha
+ * dele, e a pasta apenas pré-marca.
  */
-async function wireMcpAt(root, version, rel) {
+async function wireMcpAt(root, rel) {
     const path = join(root, rel);
     const config = await readJson(path);
     const servers = (config.mcpServers ?? {});
@@ -209,19 +211,24 @@ async function wireMcpAt(root, version, rel) {
     return replacing ? "updated" : "added";
 }
 /**
- * Os caminhos de MCP que este repo merece: sempre o do Claude Code, e o do Cursor quando `.cursor/`
- * já existe. Devolve o que foi escrito, por caminho, para o `connect` poder dizer os nomes.
+ * Os caminhos de MCP que ELE ESCOLHEU - um por agente marcado, e nada dos outros. Devolve o que foi
+ * escrito, por caminho, para o `connect` poder dizer os nomes.
  */
-async function wireMcp(root, version) {
+/**
+ * E NENHUM DOS TRÊS RECEBE VERSÃO, desde 10/09 - o parâmetro morreu quando o Codex passou a seguir
+ * a régua de `@latest` (ver `codex-mcp.ts`). Os escritores de JSON nunca a usaram: a decisão de
+ * 06/08 é que o MCP flutua. Um argumento que ninguém lê é o próximo a ser lido por engano.
+ */
+async function wireMcp(root, agents) {
     const wrote = [];
-    wrote.push({
-        path: ".mcp.json",
-        status: await wireMcpAt(root, version, ".mcp.json"),
-    });
-    if (await exists(join(root, ".cursor")))
+    /**
+     * O `.mcp.json` É DO CLAUDE CODE, e por isso ele entrou na régua (A2 da etapa 12). Era o único
+     * escritor sem condição nenhuma: num repositório que só usa Codex, ele nascia de todo jeito.
+     */
+    if (agents.includes("claude"))
         wrote.push({
-            path: ".cursor/mcp.json",
-            status: await wireMcpAt(root, version, ".cursor/mcp.json"),
+            path: ".mcp.json",
+            status: await wireMcpAt(root, ".mcp.json"),
         });
     /**
      * E O CODEX, quando `.codex/` já existe - a mesma regra de evidência que decide o Cursor e a casa
@@ -231,10 +238,10 @@ async function wireMcp(root, version) {
      * região delimitada num TOML que a pessoa também edita. Ver `codex-mcp.ts` para o porquê de não
      * haver parser.
      */
-    if (await exists(join(root, ".codex")))
+    if (agents.includes("codex"))
         wrote.push({
             path: ".codex/config.toml",
-            status: await wireCodexMcp(root, version),
+            status: await wireCodexMcp(root),
         });
     return wrote;
 }
@@ -256,11 +263,13 @@ let codexWas = null;
 export function codexPinBefore() {
     return codexWas;
 }
-async function wireCodexMcp(root, version) {
+async function wireCodexMcp(root) {
     const path = join(root, ".codex", "config.toml");
     const current = await readFile(path, "utf8").catch(() => null);
     const had = current != null && hasCodexBlock(current);
-    const next = withCodexBlock(current ?? "", version);
+    /** A MESMA pergunta que o escritor de JSON faz - ver `codexBlock`. */
+    const local = await exists(join(root, "node_modules", ".bin", "synthesisui"));
+    const next = withCodexBlock(current ?? "", local);
     if (current === next)
         return "already there";
     /**
@@ -274,8 +283,17 @@ async function wireCodexMcp(root, version) {
     return had ? "updated" : "added";
 }
 export async function wireAgent(root, version, want) {
+    /**
+     * A ESCOLHA DELE DECIDE QUEM É FIADO (A2 da etapa 12) - ver `agents-chosen.ts`.
+     *
+     * O hook e a verificação de abertura moram no `.claude/settings.json`, então eles são do Claude
+     * Code: num repositório onde ele não escolheu o Claude Code, escrever aquele arquivo é plantar a
+     * fiação de uma ferramenta que ninguém pediu. Medido em 10/09: eram 8 arquivos dele num repo que
+     * só provava o Codex.
+     */
+    const claude = want.agents.includes("claude");
     const proposed = await hookCommand(root, version);
-    const hook = want.hook
+    const hook = want.hook && claude
         ? await wireHook(root, proposed)
         : { status: "skipped", command: proposed, was: undefined };
     return {
@@ -289,10 +307,10 @@ export async function wireAgent(root, version, want) {
          * único hook instalado rodava DEPOIS de uma escrita - tarde demais para dizer "você não está
          * logado" ou "este sistema não sabe de onde foi medido".
          */
-        session: want.hook
+        session: want.hook && claude
             ? await wireSessionStart(root, await alignCommand(root, version))
             : "skipped",
-        mcp: want.mcp ? await wireMcp(root, version) : "skipped",
+        mcp: want.mcp ? await wireMcp(root, want.agents) : "skipped",
     };
 }
 /**

package/dist/agents-chosen.js

@@ -0,0 +1,246 @@
+/**
+ * QUAIS AGENTES ENTRAM NO REPOSITÓRIO DELE - e a resposta é a ESCOLHA dele, não a nossa dedução.
+ *
+ * O QUE ELE GANHA: nenhum arquivo de uma ferramenta que ele não usa. MEDIDO em 10/09, com o
+ * `connect` de verdade num repositório que só tem `.codex/`: **10 arquivos escritos, e 8 do Claude
+ * Code** - `.claude/settings.json`, cinco skills, `.mcp.json` e `CLAUDE.md`. A régua da evidência
+ * já existia e protegia o Codex e o Cursor; o Claude Code era escrito sempre, sem prova nenhuma.
+ *
+ * A DECISÃO DELE, 10/09: *"seria legal o próprio connect eu selecionar quais agentes eu quero
+ * colocar"*. Então a evidência deixa de DECIDIR e passa a PRÉ-MARCAR - ela continua sendo a melhor
+ * informação que a gente tem sobre o repositório dele, e deixa de ser a palavra final.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * DE ONDE A ESCOLHA VEM, e a saída SEMPRE diz qual dos três foi:
+ *
+ *     flag        ele mandou (`--agents claude,codex`, ou `--agents none`)
+ *     asked       ele confirmou ou mudou a lista pré-marcada, num terminal
+ *     evidence    não havia ninguém para perguntar - CI, pipe, agente -, então a pasta que
+ *                 existe decide, e a linha DIZ que foi ela
+ *
+ * O silêncio nunca é escolha: um comando que não pode perguntar e escreve tudo é o defeito que
+ * este módulo existe para acabar, e um que não pode perguntar e não escreve nada quebraria o CI de
+ * quem já usa. A evidência é o meio-termo que já era o comportamento de duas das ferramentas.
+ *
+ * A LISTA É DO PRODUTO, e é curta de propósito: o nome de uma ferramenta não decide nada sozinho -
+ * o que decide é o que ELE escolheu. O Cursor saiu em 10/09 por decisão dele (ver
+ * `cursor-is-retired.spec.ts`), e uma quarta ferramenta é ESCOPO DE CAPACIDADE: ela entra quando o
+ * produto passar a suportá-la, e essa pergunta é dele.
+ */
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+export const AGENTS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        evidence: ".claude",
+        writes: [
+            /** O hook e a verificação de abertura moram aqui, junto dos hooks DELE. */
+            { path: ".claude/settings.json", ours: "entry" },
+            /** Junto dos outros servidores MCP dele. */
+            { path: ".mcp.json", ours: "entry" },
+            { path: "CLAUDE.md", ours: "block" },
+            /** A pasta é nossa inteira: o conteúdo é o nosso texto, e ninguém edita skill gerada. */
+            { path: ".claude/skills/", ours: "file" },
+        ],
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        evidence: ".codex",
+        writes: [
+            /** O `[tui]` dele mora neste arquivo - ver `Ours`. */
+            { path: ".codex/config.toml", ours: "block" },
+            { path: "AGENTS.md", ours: "block" },
+        ],
+    },
+];
+const exists = (p) => access(p).then(() => true, () => false);
+/** O que o repositório PROVA - a pré-marcação, nunca a decisão. */
+export async function detected(root) {
+    const out = [];
+    for (const agent of AGENTS)
+        if (await exists(join(root, agent.evidence)))
+            out.push(agent.id);
+    return out;
+}
+/**
+ * O QUE ELE DIGITOU, lido do jeito mais largo possível - `claude,codex`, `claude codex`, `CLAUDE`.
+ *
+ * Um nome que a lista não conhece é DEVOLVIDO em `unknown` em vez de ignorado: ignorar em silêncio
+ * é o que faz alguém escrever `--agents cursor` e concluir que o comando obedeceu.
+ */
+export function parseAgents(raw) {
+    const words = raw
+        .split(/[\s,]+/)
+        .map((w) => w.trim().toLowerCase())
+        .filter(Boolean);
+    if (words.length === 1 && words[0] === "none")
+        return { agents: [], unknown: [], none: true };
+    const agents = [];
+    const unknown = [];
+    for (const word of words) {
+        const hit = AGENTS.find((a) => a.id === word);
+        if (hit) {
+            if (!agents.includes(hit.id))
+                agents.push(hit.id);
+        }
+        else
+            unknown.push(word);
+    }
+    return { agents, unknown, none: false };
+}
+/** Os arquivos que a fiação de um agente escreve - `[]` para um id que a lista não conhece. */
+export const filesOf = (id) => AGENTS.find((a) => a.id === id)?.writes ?? [];
+/**
+ * QUAIS AGENTES JÁ ESTÃO FIADOS NESTE REPOSITÓRIO - a memória da escolha, e ela é o próprio disco.
+ *
+ * A PREMISSA, declarada na abertura da etapa 12: a escolha é lembrada pelo que EXISTE no
+ * repositório, sem arquivo de preferência nosso. Um arquivo desses no repositório dele
+ * contraria a seção 0 da jornada, e `~/.synthesisui/` é preferência de MÁQUINA - a escolha é do
+ * projeto, e vai para outra máquina com o `git clone`.
+ *
+ * O TESTE É A NOSSA MARCA, nunca a existência do arquivo. Um `CLAUDE.md` existe em muitos
+ * repositórios sem ter uma linha nossa dentro, e `.codex/config.toml` é arquivo DELE com a nossa
+ * região no meio - concluir "está fiado" de um arquivo que a gente não escreveu faria os comandos de
+ * manutenção reescreverem a fiação de um agente que ele nunca escolheu.
+ *
+ * QUEM USA ISTO: os comandos que MANTÊM o que já existe (`add`, `adopt`, `upgrade`) - eles não
+ * perguntam nada, e a resposta certa para eles é *"continue com quem já está aqui"* - e a
+ * PRÉ-MARCAÇÃO da lista do `connect`, porque desmarcar não apaga a pasta: sem isto, a rodada
+ * seguinte re-marcava o que ele tinha acabado de tirar (revisão de DX, 10/09).
+ */
+export async function wiredAgents(root) {
+    const { readFile } = await import("node:fs/promises");
+    const has = async (rel, mark) => {
+        const raw = await readFile(join(root, rel), "utf8").catch(() => null);
+        return raw?.includes(mark) === true;
+    };
+    const out = [];
+    if ((await has(".mcp.json", "synthesisui")) ||
+        (await has("CLAUDE.md", MARK)) ||
+        (await has(".claude/settings.json", "synthesisui")))
+        out.push("claude");
+    if ((await has(".codex/config.toml", "synthesisui")) ||
+        (await has("AGENTS.md", MARK)))
+        out.push("codex");
+    return out;
+}
+/** A marca do bloco gerido - a mesma de `claude-md.ts`, e a única prova de que o texto é nosso. */
+const MARK = "<!-- synthesisui:start -->";
+/**
+ * A ESCOLHA, RESOLVIDA - e a saída sempre diz de onde ela veio.
+ *
+ * Três caminhos, e a ordem é a da autoridade: o que ele MANDOU vence o que ele CONFIRMA, que vence
+ * o que a pasta prova. `ask` é injetado para o `connect` decidir se há alguém para perguntar - um
+ * módulo que consulta `process.stdin` por conta própria não tem como ser provado sem um terminal.
+ */
+export async function chooseAgents(input) {
+    if (input.flag != null && input.flag.trim() !== "") {
+        const read = parseAgents(input.flag);
+        return { agents: read.agents, from: "flag", unknown: read.unknown };
+    }
+    /**
+     * A PRÉ-MARCAÇÃO É O QUE ESTÁ FIADO, quando há algo fiado - e só então a pasta.
+     *
+     * O DEFEITO, achado pela revisão de DX no fecho: a pré-marcação usava só a pasta, e desmarcar não
+     * apaga a pasta (é a decisão dele). Então a rodada seguinte re-marcava o que ele tinha acabado de
+     * tirar, e `Enter` - que a tela chama de *"keeps this"* - revertia a escolha dele sem ele digitar
+     * nada. A premissa desta etapa já dizia o certo: *"a escolha é derivada do que EXISTE no
+     * repositório (os arquivos fiados são a memória)"*.
+     *
+     * A ordem é a da autoridade, como em todo este módulo: o que ele REGISTROU vence o que sobrou no
+     * disco, que vence o que a pasta sugere - ver `rememberedChoice`, que é o que distingue "ele
+     * desmarcou" de "sobrou arquivo". Num repositório sem fiação nenhuma - o primeiro contato - não
+     * há escolha anterior, e aí a pasta é a melhor informação que existe.
+     */
+    const remembered = await rememberedChoice(input.root);
+    const wired = await wiredAgents(input.root);
+    const pre = remembered ?? (wired.length > 0 ? wired : await detected(input.root));
+    if (!input.ask)
+        return { agents: pre, from: "evidence", unknown: [] };
+    const typed = await input.ask(pre);
+    /** Enter mantém a pré-marcação - a confirmação é uma tecla, e continua sendo escolha dele. */
+    if (typed.trim() === "")
+        return { agents: pre, from: "asked", unknown: [] };
+    const read = parseAgents(typed);
+    return { agents: read.agents, from: "asked", unknown: read.unknown };
+}
+/**
+ * A ESCOLHA REGISTRADA - e é ela que distingue "ele desmarcou" de "sobrou arquivo no disco".
+ *
+ * O DEFEITO QUE ISTO CONSERTA, medido pela revisão de QA no fecho da etapa 12, e ele é o caso que
+ * originou a jornada: quem JÁ TEM os oito arquivos do Claude Code e os desmarca. `wiredAgents` lê a
+ * nossa marca nos arquivos - e A5 promete que desmarcar NÃO apaga arquivo nenhum. Então a memória
+ * respondia "fiado" para exatamente quem tinha acabado de dizer "não quero":
+ *
+ * ```
+ * 1) escolhe claude                wiredAgents -> [claude]
+ * 2) roda de novo, desmarca claude wiredAgents -> [claude, codex]   <- a sobra fala por ele
+ * 3) a rodada seguinte pre-marca   -> [claude, codex]
+ * 4) `Enter` ("keeps this") devolve o que ele tirou
+ * ```
+ *
+ * E o `upgrade` andava pela mesma porta: ele mantém `wiredAgents`, então re-pinava o hook que ele
+ * tinha recusado - a gente não só não parava, a gente ATUALIZAVA o que ele recusou.
+ *
+ * A PREMISSA DA ABERTURA JÁ TINHA ESCRITO A SAÍDA: *"a escolha é derivada do que EXISTE no
+ * repositório... se estiver errado: nasce um campo em `_synthesisui/config.json`, que já é nosso e
+ * já está no repo dele"*. A medição provou que estava errada, e este é o campo.
+ *
+ * ELE VAI NO REPOSITÓRIO, e não na máquina: a escolha é do PROJETO - vai junto no `git clone`, e o
+ * time inteiro herda. `~/.synthesisui/` é preferência de máquina, e seria a resposta errada aqui.
+ *
+ * A leitura e a escrita preservam o resto do arquivo: `config.json` é nosso, mas carrega o alvo, as
+ * pastas e o modo de estilo dele, e reserializar o objeto inteiro a partir de um tipo parcial
+ * apagaria campo que um CLI mais novo grave.
+ */
+const CONFIG = ["_synthesisui", "config.json"];
+export async function rememberedChoice(root) {
+    const { readFile } = await import("node:fs/promises");
+    const raw = await readFile(join(root, ...CONFIG), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.agents))
+            return null;
+        /** Um nome que a lista não conhece mais - um Cursor gravado antes da retirada - some aqui. */
+        return parsed.agents.filter((a) => AGENTS.some((known) => known.id === a));
+    }
+    catch {
+        return null;
+    }
+}
+export async function rememberChoice(root, agents) {
+    const { mkdir, readFile, writeFile } = await import("node:fs/promises");
+    const path = join(root, ...CONFIG);
+    const raw = await readFile(path, "utf8").catch(() => null);
+    let current = {};
+    if (raw) {
+        try {
+            current = JSON.parse(raw);
+        }
+        catch {
+            /** Um config ilegível não é apagado por nós - a escolha simplesmente não é lembrada. */
+            return;
+        }
+    }
+    await mkdir(join(root, CONFIG[0]), { recursive: true }).catch(() => { });
+    await writeFile(path, `${JSON.stringify({ ...current, agents: [...agents] }, null, 2)}\n`, "utf8");
+}
+/**
+ * COM QUEM OS COMANDOS DE MANUTENÇÃO CONTINUAM - `add`, `adopt`, `upgrade`.
+ *
+ * A ordem é a da autoridade: o que ele REGISTROU vence o que sobrou no disco, que vence a pasta.
+ * O último degrau existe para o primeiro contato - um `adopt` num repositório que nunca viu o
+ * `connect` não pode ficar sem casa nenhuma, senão o comando escreve o sistema e diz *"seu agente
+ * agora conhece o seu sistema"* sobre um repositório onde nenhum agente lê nada (medido em 10/09).
+ */
+export async function agentsToMaintain(root) {
+    const remembered = await rememberedChoice(root);
+    if (remembered)
+        return remembered;
+    const wired = await wiredAgents(root);
+    return wired.length > 0 ? wired : await detected(root);
+}

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 { exists, hasHook } from "./agent-wiring.js";
+import { hasHook } from "./agent-wiring.js";
 import { declaredReference } from "./group-role.js";
 import { recallAvailable } from "./memory/availability.js";
 const START = "<!-- synthesisui:start -->";
@@ -564,28 +564,39 @@ _Block managed by the CLI - do not edit by hand; run \`synthesisui ${onlyAdopted
  * ONDE O BLOCO GERENCIADO MORA, POR AGENTE.
  *
  * O bloco é o mesmo texto - as regras que um agente lê ANTES de escrever UI - e cada ferramenta
- * escolheu um arquivo diferente para lê-lo. Escrever nos três custa dois `writeFile` a mais e
+ * escolheu um arquivo diferente para lê-lo. Escrever nos dois custa um `writeFile` a mais e
  * multiplica os editores cobertos sem escrever motor novo, que era a lacuna mais barata da análise de
  * DX (05/08): a governança só chegava a quem usa Claude Code.
  *
- * `AGENTS.md` é o nome que Codex e vários outros leem; `.cursor/rules/*.mdc` é o do Cursor, e ele
- * exige frontmatter com `alwaysApply` senão a regra fica dormindo até alguém citá-la.
+ * `CLAUDE.md` é o do Claude Code; `AGENTS.md` é o nome que Codex e vários outros leem. O
+ * `.cursor/rules/*.mdc` do Cursor saiu em 10/09, por decisão dele - ver `agents-chosen.ts`.
+ *
+ * E QUEM DECIDE QUAIS DESTAS CASAS SÃO ESCRITAS É A ESCOLHA DELE (A2 da etapa 12), não a pasta:
+ * `syncClaudeMd` recebe os agentes marcados. A pasta continua sendo a melhor pré-marcação que a
+ * gente tem, e deixou de ser a palavra final.
  */
 const HOMES = [
-    { path: "CLAUDE.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",
-    },
+    { path: "CLAUDE.md", agent: "claude" },
+    { path: "AGENTS.md", agent: "codex" },
 ];
-export async function syncClaudeMd(projectRoot) {
+export async function syncClaudeMd(projectRoot, 
+/**
+ * OS AGENTES QUE ELE ESCOLHEU - e é a escolha que autoriza cada casa (A2 da etapa 12).
+ *
+ * Argumento OBRIGATÓRIO, e não opcional com default: um default aqui seria a régua velha
+ * sobrevivendo escondida no dia em que um chamador novo esquecer de passar a escolha - e a régua
+ * velha é exatamente o que fazia 8 arquivos do Claude Code entrarem num repositório de quem usa
+ * Codex. O `tsc` recusa a meia-chamada (lei 6: fechar a porta em vez de vigiá-la).
+ */
+agents) {
     const installed = await readInstalled(projectRoot);
     const region = await renderRegion(projectRoot, installed);
     let createdAny = false;
     const changed = [];
     for (const home of HOMES) {
+        /** A casa de um agente que ele não escolheu não é escrita nem reescrita. */
+        if (!agents.includes(home.agent))
+            continue;
         const path = join(projectRoot, home.path);
         let existing = null;
         try {
@@ -594,20 +605,7 @@ export async function syncClaudeMd(projectRoot) {
         catch {
             existing = null;
         }
-        /**
-         * O ARQUIVO NOVO NASCE QUANDO O REPOSITÓRIO JÁ MOSTROU QUEM ELE USA - ver `bornWhen`.
-         *
-         * `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) {
-            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");
             createdAny = true;
@@ -666,9 +664,16 @@ const OPENS = {
 /**
  * Os comandos que abrem os agentes que ESTE repositório mostra ter - vazio quando nenhum deles
  * carrega o bloco, e aí a saída não fala de abrir nada.
+ *
+ * E FILTRADO PELA ESCOLHA quando quem chama a conhece (etapa 12): o bloco de um agente desmarcado
+ * CONTINUA no arquivo, porque desmarcar não apaga nada. Sem o filtro, a tela recomendava abrir a
+ * ferramenta que ele tinha acabado de tirar - achado da revisão de QA, 10/09.
  */
-export async function agentOpenCommands(projectRoot) {
-    const homes = await blockHomes(projectRoot);
+export async function agentOpenCommands(projectRoot, agents) {
+    const allowed = agents
+        ? new Set(HOMES.filter((h) => agents.includes(h.agent)).map((h) => h.path))
+        : null;
+    const homes = (await blockHomes(projectRoot)).filter((h) => allowed === null || allowed.has(h));
     return homes.map((h) => OPENS[h]).filter((c) => Boolean(c));
 }
 export async function blockHomes(projectRoot) {

package/dist/codex-mcp.js

@@ -36,8 +36,10 @@ export function hasCodexBlock(text) {
 /**
  * A versão pinada dentro da nossa região - `null` quando não há região ou quando ela não pina.
  *
- * O `connect` usa isto para dizer de ONDE para onde a fiação andou, que é a diferença entre
- * "atualizei" e uma linha que a pessoa fecha sem ler.
+ * O `connect` usa isto para dizer de ONDE a fiação saiu, que é a diferença entre "atualizei" e uma
+ * linha que a pessoa fecha sem ler. Desde 10/09 a região nova nunca pina (ver `codexBlock`), então
+ * o que esta função encontra é sempre PASSADO - e é exatamente aí que ela vale mais: um arquivo que
+ * ainda diz `synthesisui@0.16.413` está preso naquele leitor, e a tela pode dizer que ele saiu.
  */
 export function pinnedInCodex(text) {
     const start = text.indexOf(BEGIN);
@@ -50,14 +52,36 @@ export function pinnedInCodex(text) {
 /**
  * A REGIÃO, montada. `args` em duas partes porque é assim que o Codex quer a linha de comando:
  * o executável em `command`, e o resto quebrado em array.
+ *
+ * A MESMA RÉGUA DE VERSÃO DO OUTRO ESCRITOR, e isto é um conserto de 10/09. Este bloco nascia
+ * PINADO na versão do `connect`, e o `.mcp.json` do Claude Code nasce em `@latest` desde 06/08 -
+ * duas ferramentas, o mesmo repositório, o mesmo servidor nosso, e respostas opostas sobre quando
+ * ele fica mais novo.
+ *
+ * A decisão está escrita em `agent-wiring.ts`, e vale para os dois pela mesma razão: *"um servidor
+ * MCP sobe UMA VEZ quando o editor abre a sessão e fica estável durante ela. Pinado, ele nunca
+ * ficava mais novo - e a regra que manda o agente comparar `ledger.cli` com a versão do servidor
+ * quase nunca disparava, porque os dois congelavam juntos no dia do `connect`"* (dono, 06/08). O
+ * hook é o caso oposto e continua pinado: ele resolve a CADA escrita, e ali flutuar custa 720ms-1,5s
+ * por edição e um comportamento que muda sob a pessoa.
+ *
+ * O QUE O CLIENTE PERCEBIA: o agente dele no Claude Code recebia o leitor publicado na sessão
+ * seguinte; o agente dele no Codex ficava na versão do dia em que ele rodou o `connect`, e nada na
+ * tela dizia que os dois estavam em versões diferentes.
+ *
+ * E O INSTALL LOCAL CONTINUA GANHANDO, também como no outro: quem tem o CLI no `node_modules`
+ * escolheu a versão, e `--no-install` respeita a escolha - inclusive a de quem seguiu a sugestão
+ * que o próprio `connect` imprime, de pôr o CLI nas `devDependencies`.
  */
-export function codexBlock(version) {
+export function codexBlock(local) {
     return [
         BEGIN,
         "# Managed by synthesisui. Edit outside this block; this region is rewritten on connect.",
         "[mcp_servers.synthesisui]",
         'command = "npx"',
-        `args = ["synthesisui@${version}", "mcp"]`,
+        local
+            ? 'args = ["--no-install", "synthesisui", "mcp"]'
+            : 'args = ["synthesisui@latest", "mcp"]',
         END,
     ].join("\n");
 }
@@ -73,8 +97,8 @@ export function codexBlock(version) {
  * perdeu. Aí a gente devolve o arquivo COMO ESTÁ: apagar até o fim seria destruir o que vem
  * depois, e é a mesma decisão que o `withHook` toma no perfil de shell.
  */
-export function withCodexBlock(text, version) {
-    const block = codexBlock(version);
+export function withCodexBlock(text, local) {
+    const block = codexBlock(local);
     if (!hasCodexBlock(text))
         return `${text.replace(/\n*$/, "")}\n\n${block}\n`.replace(/^\n+/, "");
     const start = text.indexOf(BEGIN);

package/dist/commands/add.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
@@ -432,7 +433,7 @@ export async function add(slug, opts) {
      * (`doctrine.json`): o doctor e o hook precisam delas offline.
      */
     // 6. discovery by the agent
-    const claudeMd = await syncClaudeMd(projectRoot);
+    const claudeMd = await syncClaudeMd(projectRoot, await agentsToMaintain(projectRoot));
     // outcome line
     const v = payload.version;
     if (!prev) {

package/dist/commands/adopt.js

@@ -1,8 +1,9 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { parseRootTokens } from "../doctor/tokens.js";
-import { body, section, snippet } from "../output.js";
+import { body, paint, section, snippet } from "../output.js";
 import { walk } from "./doctor.js";
 /**
  * `synthesisui adopt` - the system somebody ALREADY has, made legible.
@@ -239,12 +240,27 @@ export async function adopt(opts) {
     // `version: 0` marks a system nobody published - the doctor and CLAUDE.md
     // read this to know it is adopted rather than installed.
     await writeFile(join(dir, ".lock"), `${JSON.stringify({ slug, name, version: 0, adopted: true }, null, 2)}\n`, "utf8");
-    await syncClaudeMd(root);
+    /**
+     * A LINHA SAI DO QUE FOI ESCRITO, e não de uma promessa fixa - achado da revisão de QA no fecho
+     * da etapa 12, e é uma regressão que ela mesma criou.
+     *
+     * Desde que as casas do bloco passaram a obedecer à escolha dele, um repositório de PRIMEIRO
+     * CONTATO - nenhuma escolha registrada, nenhuma pasta de agente - não recebe casa nenhuma. E
+     * estas três linhas eram fixas: o comando dizia `✓ CLAUDE.md managed block added` e *"seu agente
+     * agora conhece o seu sistema"* sobre um repositório onde nenhum agente lê nada. O `adopt` é a
+     * porta que a home anuncia para quem quer o contrato sem conta.
+     */
+    const claudeMd = await syncClaudeMd(root, await agentsToMaintain(root));
     console.log("");
     console.log(body(`✓ _synthesisui/ds/${slug}/  written`));
-    console.log(body("✓ CLAUDE.md              managed block added"));
+    for (const home of claudeMd.changed)
+        console.log(body(`✓ ${home.padEnd(22)} managed block added`));
     console.log("");
-    console.log(body("Your agent now knows your system. Nothing of yours changed."));
+    console.log(body(claudeMd.changed.length > 0
+        ? "Your agent now knows your system. Nothing of yours changed."
+        : "Nothing of yours changed - and no agent home was written, because this repo does not say which agent you use yet:"));
+    if (claudeMd.changed.length === 0)
+        console.log(body(paint.blue("  npx synthesisui@latest connect")));
     console.log("");
     console.log(snippet(["npx synthesisui@latest doctor"]));
     console.log(body("see what it makes measurable"));

package/dist/commands/align.js

@@ -712,7 +712,13 @@ opts = {}) {
  * repositório inteiro, e isto roda em TODA abertura de sessão. Um aviso que custa um walk completo
  * a cada sessão é um aviso que alguém desliga.
  */
-export async function nextStepFor(root) {
+export async function nextStepFor(root, 
+/**
+ * OS AGENTES QUE ELE ESCOLHEU, quando quem chama sabe (etapa 12) - o bloco de um agente
+ * desmarcado continua no arquivo, porque desmarcar não apaga nada, e sem este filtro a tela
+ * recomendava abrir a ferramenta que ele tinha acabado de tirar.
+ */
+agents) {
     const locks = (await locksIn(root)).filter((l) => l.slug && !l.adopted);
     if (locks.length > 0)
         return null;
@@ -742,7 +748,7 @@ export async function nextStepFor(root) {
         : {
             sentence: 'This repo has no design system contract yet. Ask me: "import my design system."',
             headline: "Open a new agent session in this repo",
-            open: await agentOpenCommands(root).catch(() => []),
+            open: await agentOpenCommands(root, agents).catch(() => []),
             say: "import my design system",
             why: "I read what is already in your code - the colours, the type, the shapes, the components. Nothing is invented.",
         };
@@ -830,7 +836,7 @@ export function renderNextStep(next, freshSession) {
  */
 export async function reportWhatIsLeft(root, opts = {}) {
     const items = await misalignments(root, opts).catch(() => []);
-    const next = await nextStepFor(root).catch(() => null);
+    const next = await nextStepFor(root, opts.agents).catch(() => null);
     /**
      * A AÇÃO RECOMENDADA GANHA DA LISTA - e a falta desta regra foi a regressão que o dono leu na
      * 0.16.365.

package/dist/commands/connect.js

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { codexPinBefore, wireAgent } from "../agent-wiring.js";
+import { codexPinBefore, exists, wireAgent } from "../agent-wiring.js";
+import { AGENTS, chooseAgents, filesOf, rememberChoice, } from "../agents-chosen.js";
 import { blockHomes, syncClaudeMd } from "../claude-md.js";
 import { resolveRegistry } from "../config.js";
 import { notAProject, projectRootFrom } from "../is-a-project.js";
@@ -211,6 +212,53 @@ version) {
     await writeFile(rc, withHook(current ?? "", shellSnippet(shell, version)), "utf8");
     console.log(body(`Written. Open a new terminal, or run: source ${rc}`));
 }
+/**
+ * A LISTA, E ELE DECIDE (A1 da etapa 12) - com o que o repositório PROVA já marcado.
+ *
+ * A pré-marcação é a evidência: ela continua sendo a melhor informação que a gente tem sobre o
+ * repositório dele, e deixou de ser a palavra final. Enter confirma - a confirmação é uma tecla, e
+ * continua sendo escolha dele -, e digitar os nomes substitui a lista.
+ *
+ * SEM BIBLIOTECA DE CHECKBOX, de propósito: um seletor com setas exige controlar o terminal em raw
+ * mode, e este comando roda em terminal de CI, em terminal dentro de editor e em terminal de quem
+ * usa Windows. Uma linha por agente e uma pergunta é o que funciona nos três.
+ */
+async function askWhichAgents(pre) {
+    console.log("");
+    console.log(section(say("Which agents")));
+    for (const agent of AGENTS) {
+        const on = pre.includes(agent.id);
+        console.log(body(`${on ? "[x]" : "[ ]"} ${agent.label.padEnd(13)} ${on
+            ? fmt(say("{dir} is here"), { dir: agent.evidence })
+            : fmt(say("no {dir} in this repo"), { dir: agent.evidence })}`));
+    }
+    console.log("");
+    console.log(body(say("Enter keeps this. To change it, type the ones you want - or `none`:")));
+    console.log(body(paint.faint(`  ${AGENTS.map((a) => a.id).join(" ")}`)));
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const typed = await rl.question("  > ").catch(() => "");
+    rl.close();
+    return typed;
+}
+/**
+ * O QUE FICOU ESCOLHIDO, ecoado antes de agir - achado da revisão de DX no fecho.
+ *
+ * A frase da lista já diz que digitar SUBSTITUI o conjunto, e o risco não é de vocabulário: é de
+ * hábito. Quem está acostumado com seletor incremental vê `[x] Codex` marcado, digita `claude`
+ * querendo acrescentar, e perde o Codex. A consequência aparecia embaixo, misturada com as outras
+ * linhas; uma linha só, antes de qualquer escrita, torna o engano visível no lugar onde ele
+ * aconteceu.
+ */
+function echoChoice(agents) {
+    console.log("");
+    console.log(body(fmt(say("Selected: {agents}"), {
+        agents: agents.length > 0 ? agents.join(" ") : "none",
+    })));
+}
 export async function connect(opts) {
     const root = opts.dir ?? process.cwd();
     /**
@@ -234,7 +282,36 @@ export async function connect(opts) {
     }
     // Both unless one is explicitly turned off - somebody who says `--no-hook`
     // means it, and somebody who says nothing wants the thing to work.
-    const want = { hook: opts.hook !== false, mcp: opts.mcp !== false };
+    const layers = { hook: opts.hook !== false, mcp: opts.mcp !== false };
+    /**
+     * QUAIS AGENTES ENTRAM - a escolha DELE, e nunca a nossa dedução (A1..A4 da etapa 12).
+     *
+     * MEDIDO em 10/09, com este comando num repositório que só tem `.codex/`: 10 arquivos escritos, e
+     * 8 do Claude Code. A régua da evidência protegia o Codex e o Cursor; o Claude Code era escrito
+     * sempre. A decisão dele: *"seria legal o próprio connect eu selecionar quais agentes eu quero
+     * colocar"*.
+     *
+     * A PERGUNTA SÓ EXISTE ONDE HÁ ALGUÉM PARA RESPONDER. Em `--ci`, num pipe ou dentro de um agente,
+     * `ask` vai `null` e a pasta decide - e a linha DIZ que foi ela, porque silêncio nunca é escolha.
+     */
+    const interactive = !opts.ci && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    const chosen = await chooseAgents({
+        root,
+        flag: opts.agents,
+        ask: interactive ? (pre) => askWhichAgents(pre) : null,
+    });
+    const want = { ...layers, agents: chosen.agents };
+    if (chosen.from === "asked")
+        echoChoice(chosen.agents);
+    /**
+     * A ESCOLHA FICA REGISTRADA quando foi ELE quem a fez - ver `rememberChoice`.
+     *
+     * Só `asked` e `flag`: uma dedução da pasta não é escolha, e gravá-la faria a próxima rodada
+     * tratar o palpite de hoje como decisão dele. É a mesma linha que separa `from: "evidence"` dos
+     * outros dois em toda esta etapa.
+     */
+    if (chosen.from !== "evidence")
+        await rememberChoice(root, chosen.agents).catch(() => { });
     /**
      * OS ARQUIVOS DO INSTALL ANTES DA FIAÇÃO: o `add` reescreve o `CLAUDE.md` por dentro, e o
      * `syncClaudeMd` abaixo tem que ser o último a falar sobre ele.
@@ -251,8 +328,26 @@ export async function connect(opts) {
     const wired = await wireAgent(root, opts.version, want);
     // The block reads the settings we just wrote, so it must be regenerated
     // after them, not before.
-    const contract = await syncClaudeMd(root);
+    const contract = await syncClaudeMd(root, chosen.agents);
     console.log(section(say("Connected")));
+    /**
+     * NENHUM AGENTE ESCOLHIDO NÃO É COMANDO QUEBRADO (A3) - a frase diz o que falta e o caminho.
+     *
+     * Um comando que não escreve nada e não explica lê como defeito. E o caso é real: um repositório
+     * sem `.claude/` e sem `.codex/` não prova ferramenta nenhuma, e num CI não há quem responder.
+     */
+    if (chosen.agents.length === 0)
+        console.log(body(say(chosen.from === "evidence"
+            ? "· no agent chosen, and nothing here says which agent you use - run with `--agents claude` or `--agents codex`, or run this in a terminal to pick from the list"
+            : "· no agent chosen - nothing was wired. Run again with `--agents claude` or `--agents codex` when you want it")));
+    /** E DE ONDE A ESCOLHA VEIO, quando não foi ele quem respondeu: silêncio não é escolha. */
+    if (chosen.agents.length > 0 && chosen.from === "evidence")
+        console.log(body(paint.faint(fmt(say("· nobody to ask here, so the folders in this repo decided: {agents}"), { agents: chosen.agents.join(", ") }))));
+    /** UM NOME QUE A LISTA NÃO CONHECE VOLTA DITO - engoli-lo faria `--agents cursor` parecer aceito. */
+    if (chosen.unknown.length > 0)
+        console.log(body(fmt(say("· not an agent this CLI knows: {names}"), {
+            names: chosen.unknown.join(", "),
+        })));
     /**
      * A LISTA DA TELA, JUNTADA ANTES DE IMPRIMIR - e é isto que faz a rodada silenciosa caber numa
      * linha.
@@ -327,7 +422,16 @@ export async function connect(opts) {
         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"}`);
-    if (want.hook) {
+    /**
+     * O HOOK É DO CLAUDE CODE, então a linha dele só sai quando ele foi escolhido (etapa 12).
+     *
+     * MEDIDO na primeira rodada real desta etapa, num repositório que só prova o Codex: a tela dizia
+     * `· Claude Code not chosen - nothing of it was written` e, três linhas abaixo,
+     * `· .claude/settings.json  already had it` com o comando do hook embaixo. É a mesma contradição
+     * de duas frases que a etapa 11 fechou no `template`, aparecendo na tela que a 12 acabou de
+     * escrever - e `wired.hook` diz `skipped`, então a informação para suprimir já estava aqui.
+     */
+    if (want.hook && wired.hook !== "skipped") {
         row(wired.hook !== "already there", (() => {
             return wired.hook === "added"
                 ? say("✓ .claude/settings.json  the check now runs after every write")
@@ -367,16 +471,13 @@ export async function connect(opts) {
                 ? `✓ ${one.path.padEnd(22)} ${fmt("{n} tools the agent can ask", { n: MCP_TOOL_COUNT })}`
                 : one.status === "updated"
                     ? /**
-                       * DUAS HISTÓRIAS DIFERENTES SOB O MESMO `updated`, e dizer a errada é pior que não
-                       * dizer: no Claude Code e no Cursor a entrada é SOLTA (`@latest`), então o que
-                       * mudou é ela parar de segurar um leitor velho. No Codex a entrada é PINADA numa
-                       * versão, e o que mudou é de qual para qual - a mesma correção que o hook recebeu
-                       * em 06/08, quando "already had it" escondia um pin antigo.
+                       * O QUE MUDOU É SEMPRE A MESMA COISA AGORA: a entrada parou de segurar um leitor
+                       * velho. As três ferramentas seguem a régua de 06/08 (ver `codexBlock`), então a
+                       * frase é uma - e o Codex só ganha uma metade a mais, porque ele é o único cujo
+                       * arquivo pode estar vindo de um PIN nosso, escrito antes de 10/09.
                        */
-                        one.path.endsWith(".toml")
-                            ? `✓ ${one.path.padEnd(22)} ${fmt(codexPinBefore()
-                                ? "the tools moved from {was} to this one"
-                                : "{n} tools the agent can ask", { was: codexPinBefore() ?? "", n: MCP_TOOL_COUNT })}`
+                        one.path.endsWith(".toml") && codexPinBefore()
+                            ? `✓ ${one.path.padEnd(22)} ${fmt("was pinned to {was} - now it follows the published reader", { was: codexPinBefore() ?? "" })}`
                             : `✓ ${one.path.padEnd(22)} ${say("unpinned - it follows the published reader")}`
                     : `· ${one.path.padEnd(22)} ${say("already had it")}`);
     }
@@ -434,7 +535,18 @@ export async function connect(opts) {
      * repositório é uma skill que só nós rodamos, e o caso de uso inteiro dela é o cliente rodando
      * sozinho. Meia jornada não é meio valor.
      */
-    const skills = SKILLS;
+    /**
+     * AS SKILLS SÃO DO CLAUDE CODE, e por isso elas obedecem à escolha (A2 da etapa 12).
+     *
+     * O caminho é `.claude/skills/<nome>/SKILL.md` - a casa de UMA ferramenta. Cinco arquivos numa
+     * pasta de um editor que a pessoa não usa era metade dos 8 que a medição de 10/09 encontrou num
+     * repositório que só prova o Codex.
+     *
+     * O DIA EM QUE OUTRA FERRAMENTA TIVER SKILLS, a lista de `agents-chosen.ts` ganha o caminho dela e
+     * este laço passa a andar por agente. Hoje ela é uma, e fingir uma abstração para uma população
+     * de um é o que este repositório chama de configuração vestida de produto.
+     */
+    const skills = chosen.agents.includes("claude") ? SKILLS : [];
     /**
      * A PASTA VELHA SAI, e isto é obrigatório numa renomeação de skill distribuída.
      *
@@ -472,6 +584,82 @@ export async function connect(opts) {
     }
     /** A tela sai agora, junta: o que mudou por nome, e o silêncio numa linha. */
     flush();
+    /**
+     * O QUE ELE NÃO ESCOLHEU É DITO, com os caminhos (A2 e A5 da etapa 12) - lacuna declarada é
+     * confiança, lacuna calada é bug (lei 8).
+     *
+     * Os arquivos que a fiação daquele agente escreveria, nomeados: *"8 arquivos"* obrigaria a pessoa
+     * a adivinhar quais. E quando algum deles JÁ ESTÁ no repositório - ele desmarcou algo que estava
+     * fiado -, a linha diz que ele ficou lá e como remover a NOSSA parte: apagar arquivo dele não é
+     * nosso (decisão dele, 10/09), e o `.codex/config.toml` tem configuração DELE dentro - foi por
+     * isso que o `rm` do arquivo inteiro saiu daqui (revisão de DX, mesmo dia).
+     */
+    for (const agent of AGENTS) {
+        if (chosen.agents.includes(agent.id))
+            continue;
+        const left = [];
+        for (const wrote of filesOf(agent.id))
+            if (await exists(join(root, wrote.path.replace(/\/$/, ""))))
+                left.push(wrote);
+        console.log(body(paint.faint(left.length > 0
+            ? fmt(say("· {label} not chosen - these stay in the repo: {files}"), {
+                label: agent.label,
+                files: left.map((w) => w.path).join(", "),
+            })
+            : fmt(say("· {label} not chosen - nothing of it was written"), {
+                label: agent.label,
+            }))));
+        /**
+         * A INSTRUÇÃO DE REMOVER DEPENDE DE QUEM É O ARQUIVO - ver `Ours` em `agents-chosen.ts`.
+         *
+         * O `rm` só vale para o que a gente criou inteiro. Para o que é DELE com a nossa região dentro,
+         * a instrução é a MARCA: o `.codex/config.toml` tem a `status_line` dele, e o
+         * `.claude/settings.json` tem os hooks dele.
+         */
+        const ours = left.filter((w) => w.ours === "file").map((w) => w.path);
+        const blocks = left.filter((w) => w.ours === "block").map((w) => w.path);
+        const entries = left.filter((w) => w.ours === "entry").map((w) => w.path);
+        if (ours.length > 0)
+            console.log(body(paint.faint(`    rm -rf ${ours.join(" ")}`)));
+        if (blocks.length > 0)
+            console.log(body(paint.faint(fmt(say("    our part in {files} sits between `synthesisui:start` and `synthesisui:end` - the rest of each file is yours"), { files: blocks.join(", ") }))));
+        /**
+         * E NUM JSON NÃO HÁ MARCA PARA PROCURAR - a nossa parte é uma CHAVE. Dizer "entre as marcas"
+         * sobre o `.claude/settings.json` seria mandar procurar um botão que a tela não mostra.
+         */
+        if (entries.length > 0)
+            console.log(body(paint.faint(fmt(say("    in {files} only our `synthesisui` entry is ours - the rest of the file is yours"), { files: entries.join(", ") }))));
+        /**
+         * E O `.claude/settings.json` É O ÚNICO QUE CONTINUA RODANDO, então ele é dito à parte - achado
+         * da revisão de DX: *"these stay in the repo"* lê como arquivo inerte, e o hook lá dentro é
+         * executado pelo editor a cada escrita, escolha ou não escolha. Quem desmarcou para parar de ser
+         * interrompido precisa saber que só apagar a região para isso.
+         */
+        if (entries.includes(".claude/settings.json"))
+            console.log(body(paint.faint(say("    the write check inside it keeps running until that entry is gone"))));
+    }
+    /**
+     * O CURSOR SAIU DO PRODUTO (A6 da etapa 12), e quem tem os arquivos dele é avisado com os
+     * caminhos - por decisão dele, 10/09.
+     *
+     * A gente escrevia dois arquivos naquela pasta: `.cursor/mcp.json` (as ferramentas) e
+     * `.cursor/rules/synthesisui.mdc` (as regras). Eles ficam onde estão - apagar arquivo do
+     * repositório dele não é nosso -, e a linha diz o que eles são e o que dentro deles é nosso: o
+     * arquivo de regras é nosso inteiro, e no `.cursor/mcp.json` só a entrada `synthesisui` é.
+     *
+     * O aviso sai enquanto os arquivos estiverem lá, e é o próprio disco que decide: ele desaparece
+     * quando ele age. Sem arquivo de estado nosso para lembrar de um aviso.
+     */
+    {
+        const left = [];
+        for (const rel of [".cursor/mcp.json", ".cursor/rules/synthesisui.mdc"])
+            if (await exists(join(root, rel)))
+                left.push(rel);
+        if (left.length > 0) {
+            console.log(body(fmt(say("· Cursor is no longer wired by this CLI - what we wrote is still here: {files}"), { files: left.join(", ") })));
+            console.log(body(paint.faint(say("    the rules file is ours to delete; in `.cursor/mcp.json` only the `synthesisui` entry is - the other servers there are yours"))));
+        }
+    }
     /**
      * O CI: escrito quando pedido, e NÃO MAIS OFERECIDO aqui.
      *
@@ -527,6 +715,8 @@ export async function connect(opts) {
     ];
     await reportWhatIsLeft(root, {
         cli: opts.version,
+        /** A ação recomendada abre o que ele ESCOLHEU - ver `agentOpenCommands` (etapa 12). */
+        agents: chosen.agents,
         ...(needsRestart || skillsMoved
             ? { freshSession: { loads, mcp: mcpMoved } }
             : {}),
@@ -544,7 +734,13 @@ export async function connect(opts) {
      * 2525ms -> 295ms num repo com o pacote em `node_modules`. "Ten times" era otimista; "several" é o
      * que se sustenta.
      */
-    if (wired.command.startsWith("npx synthesisui@")) {
+    /**
+     * E SÓ QUANDO EXISTE HOOK - achado da revisão de QA no fecho da etapa 12: `wired.command` é
+     * preenchido mesmo quando o hook foi PULADO (é o comando que SERIA escrito), então num
+     * repositório que escolheu só o Codex a tela explicava o custo de um hook que não existe ali.
+     */
+    if (wired.hook !== "skipped" &&
+        wired.command.startsWith("npx synthesisui@")) {
         /**
          * O CUSTO DO HOOK, EM UMA LINHA - eram cinco, e elas fechavam a tela.
          *

package/dist/commands/upgrade.js

@@ -1,6 +1,7 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pinnedHookVersion, wireAgent } from "../agent-wiring.js";
+import { agentsToMaintain } from "../agents-chosen.js";
 import { isOlderCli } from "../cli-version.js";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
@@ -157,7 +158,18 @@ async function rewireIfBehind(root, cli) {
     const pinned = await pinnedHookVersion(root).catch(() => null);
     if (!pinned || pinned === cli)
         return;
-    await wireAgent(root, cli, { hook: true, mcp: true }).catch(() => null);
+    /**
+     * COM QUEM JÁ ESTÁ AQUI, e nunca com a lista inteira - ver `wiredAgents`.
+     *
+     * Este comando MANTÉM o que existe: ele não pergunta nada e não pode escolher por ele. Passar a
+     * lista do produto faria um `upgrade` plantar a fiação de um agente que ele nunca marcou, que é
+     * exatamente o defeito que a etapa 12 fechou no `connect`.
+     */
+    await wireAgent(root, cli, {
+        hook: true,
+        mcp: true,
+        agents: await agentsToMaintain(root),
+    }).catch(() => null);
     console.log(`↻ the check after every write moved from ${pinned} to ${cli}`);
     console.log("  Reopen your editor session - hooks are read at startup.");
 }

package/dist/copy/connect.pt-BR.js

@@ -37,9 +37,30 @@ register("pt-BR", {
     "✓ .claude/settings.json  each session opens with what is missing": "✓ .claude/settings.json  cada sessão abre com o que falta",
     "✓ .claude/settings.json  the session check moved to this one": "✓ .claude/settings.json  a verificação de sessão veio para esta",
     "· .claude/settings.json  the session check was already there": "· .claude/settings.json  a verificação de sessão já estava lá",
+    // ── a escolha dos agentes (etapa 12) ──
+    /**
+     * A LISTA E OS NOMES DOS AGENTES NÃO TRADUZEM - `claude` e `codex` são o que ele DIGITA, e a mesma
+     * razão da frase `import my design system`: onde a máquina lê, a precisão vence a gentileza.
+     */
+    "Which agents": "Quais agentes",
+    "{dir} is here": "{dir} está aqui",
+    "no {dir} in this repo": "nenhum {dir} neste repo",
+    "Enter keeps this. To change it, type the ones you want - or `none`:": "Enter mantém isto. Para mudar, digite os que você quer - ou `none`:",
+    "· {label} not chosen - these stay in the repo: {files}": "· {label} não escolhido - estes ficam no repo: {files}",
+    "· {label} not chosen - nothing of it was written": "· {label} não escolhido - nada dele foi escrito",
+    "· Cursor is no longer wired by this CLI - what we wrote is still here: {files}": "· o Cursor não é mais fiado por este CLI - o que a gente escreveu continua aqui: {files}",
+    "· nobody to ask here, so the folders in this repo decided: {agents}": "· não havia ninguém para perguntar, então as pastas deste repo decidiram: {agents}",
+    "Selected: {agents}": "Selecionados: {agents}",
+    "    our part in {files} sits between `synthesisui:start` and `synthesisui:end` - the rest of each file is yours": "    a nossa parte em {files} fica entre `synthesisui:start` e `synthesisui:end` - o resto de cada arquivo é seu",
+    "    in {files} only our `synthesisui` entry is ours - the rest of the file is yours": "    em {files} só a nossa entrada `synthesisui` é nossa - o resto do arquivo é seu",
+    "    the write check inside it keeps running until that entry is gone": "    a verificação de escrita dentro dele continua rodando até aquela entrada sair",
+    "    the rules file is ours to delete; in `.cursor/mcp.json` only the `synthesisui` entry is - the other servers there are yours": "    o arquivo de regras é nosso para apagar; no `.cursor/mcp.json` só a entrada `synthesisui` é - os outros servidores ali são seus",
+    "· not an agent this CLI knows: {names}": "· não é um agente que este CLI conhece: {names}",
+    "· no agent chosen, and nothing here says which agent you use - run with `--agents claude` or `--agents codex`, or run this in a terminal to pick from the list": "· nenhum agente escolhido, e nada aqui diz qual agente você usa - rode com `--agents claude` ou `--agents codex`, ou rode isto num terminal para escolher da lista",
+    "· no agent chosen - nothing was wired. Run again with `--agents claude` or `--agents codex` when you want it": "· nenhum agente escolhido - nada foi fiado. Rode de novo com `--agents claude` ou `--agents codex` quando quiser",
     // ── o MCP e as skills ──
     "{n} tools the agent can ask": "{n} ferramentas que o agente pode consultar",
-    "the tools moved from {was} to this one": "as ferramentas vieram da {was} para esta",
+    "was pinned to {was} - now it follows the published reader": "estava pinado na {was} - agora acompanha o leitor publicado",
     "unpinned - it follows the published reader": "solto - acompanha o leitor publicado",
     "already had it": "já estava lá",
     "already current": "já está em dia",

package/dist/index.js

@@ -62,7 +62,8 @@ Usage - governance (deterministic, FREE):
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
   synthesisui import [--scope <p>] [--usage <p>]  read what you already have and make it a system
                                            your agent follows - without touching your CSS
-  synthesisui connect [--ci]                      wire your agent: the check as an editor hook, the system
+  synthesisui connect [--agents claude,codex] [--ci]
+                                           wire the agents YOU pick: the check as an editor hook, the system
                                            as MCP tools, and a contract that stops repeating itself
   synthesisui doctor [paths…] [--verbose]  audit for DRIFT: every design value written by hand, the
                                            token your system already has for it, coherence, and the
@@ -268,6 +269,7 @@ async function main() {
                 mcp: flags.mcp !== false,
                 ci: flags.ci === true,
                 shell: flags.shell === true,
+                ...(typeof flags.agents === "string" ? { agents: flags.agents } : {}),
             });
             return;
         case "hook":

package/dist/install-marks.js

@@ -187,7 +187,34 @@
  * O que o cliente ganha ao rodar `upgrade`: os componentes que ele já tem voltam a ser reescritos
  * pelo materializador que respeita a edição dele em TODO comando, e não só em dois.
  */
-export const MATERIALISER_SINCE = "0.16.412";
+/**
+ * 0.16.412 -> 0.16.414 em 10/09: as ferramentas do sistema param de congelar no Codex. A região que
+ * a gente escreve em `.codex/config.toml` nascia PINADA na versão do `connect`, e o `.mcp.json` do
+ * Claude Code nasce solta desde 06/08 - o agente dele numa ferramenta recebia o leitor publicado na
+ * sessão seguinte, e na outra ficava no do dia em que ele rodou o comando. Medido no repositório do
+ * dono depois de um `connect` da 0.16.413: `@latest` num arquivo, `@0.16.413` no outro.
+ *
+ * São BYTES DIFERENTES na pasta dele, e o `upgrade` chama `wireAgent`: quem já instalou sai do pin
+ * rodando o comando, e a tela diz de qual versão ele saiu.
+ *
+ * O que o cliente ganha ao rodar `upgrade`: o agente dele no Codex volta a ler o interpretador
+ * publicado, em vez do que existia no dia em que ele conectou.
+ */
+/**
+ * 0.16.414 -> 0.16.415 em 10/09: o conjunto de arquivos que cai na pasta dele passa a ser o que ELE
+ * ESCOLHEU. Antes o Claude Code era escrito sempre, sem evidência nenhuma - medido no mesmo dia com
+ * o comando de verdade num repositório que só tem `.codex/`: **10 arquivos, e 8 do Claude Code**
+ * (`.claude/settings.json`, cinco skills, `.mcp.json`, `CLAUDE.md`). O Cursor saiu do produto na
+ * mesma decisão, então `.cursor/mcp.json` e `.cursor/rules/synthesisui.mdc` deixam de nascer.
+ *
+ * O `upgrade` chama `wireAgent`, e ele passa a manter APENAS quem já está fiado: um `upgrade` não
+ * pergunta nada, e plantar a fiação de um agente que ele nunca marcou seria o defeito voltando pela
+ * porta da manutenção.
+ *
+ * O que o cliente ganha ao rodar `upgrade`: nada de uma ferramenta que ele não usa é reescrito no
+ * repositório dele.
+ */
+export const MATERIALISER_SINCE = "0.16.415";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/memory/availability.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { hasCodexBlock, pinnedInCodex } from "../codex-mcp.js";
 /**
  * O RECALL ESTÁ AO ALCANCE DESTE REPOSITÓRIO? - e é isto que decide o tamanho do `CLAUDE.md`.
  *
@@ -18,8 +19,32 @@ import { join } from "node:path";
  *
  * 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. */
+/**
+ * Onde os agentes leem o servidor - o mesmo shape, dois caminhos.
+ *
+ * `.cursor/mcp.json` CONTINUA SENDO LIDO depois da retirada do Cursor em 10/09, e a diferença é
+ * escrever contra ler: o produto não põe mais nada lá, e um repositório que recebeu aquele arquivo
+ * de uma versão anterior REALMENTE tem o servidor fiado. Deixar de ler seria dizer a ele que a
+ * memória não está disponível num repositório onde ela está.
+ */
 const MCP_FILES = [".mcp.json", ".cursor/mcp.json"];
+/**
+ * E O CODEX PROVA PELO ARQUIVO DELE - achado da revisão de QA no fecho da etapa 12, e é uma
+ * regressão que ela criou.
+ *
+ * O Codex declara o servidor em TOML, sob `[mcp_servers.synthesisui]`, e esta função só lia JSON.
+ * Enquanto o `.mcp.json` nascia SEMPRE, um repositório só-Codex passava por acidente: o arquivo do
+ * Claude Code estava lá mesmo sem ninguém usar o Claude Code. Desde que a escolha dele decide, ele
+ * não nasce - e a capacidade sumiu para todo usuário de Codex.
+ *
+ * O QUE ELE VIVIA: o mesmo comando imprimia `✓ .codex/config.toml  20 tools the agent can ask` e,
+ * no `AGENTS.md` que aquele agente lê, escrevia a variante que diz que não há ferramenta nenhuma -
+ * o dobro de texto mandando ler o guia à mão. `recall` e `remember` sumiam.
+ *
+ * A pergunta desta função é CAPACIDADE, nunca nome de agente: existe, neste repositório, um lugar
+ * onde um agente lê o nosso servidor? O TOML é um desses lugares desde 03/09.
+ */
+const MCP_TOML = ".codex/config.toml";
 /** A versão em que `recall` e `remember` passaram a existir. */
 export const RECALL_SINCE = "0.16.264";
 const older = (mine, than) => {
@@ -64,6 +89,20 @@ export async function recallAvailable(root) {
             because: `the MCP server is registered in ${rel}`,
         };
     }
+    /** E O TOML DO CODEX - ver `MCP_TOML`, e o pin é lido pelo mesmo leitor que o `connect` usa. */
+    const toml = await readFile(join(root, MCP_TOML), "utf8").catch(() => null);
+    if (toml && hasCodexBlock(toml)) {
+        const pin = pinnedInCodex(toml);
+        if (pin && older(pin, RECALL_SINCE))
+            return {
+                available: false,
+                because: `the MCP server in ${MCP_TOML} 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 ${MCP_TOML}`,
+        };
+    }
     return {
         available: false,
         because: "no MCP server is registered in this repository - run `synthesisui connect` so the agent can look memory up",

package/package.json

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