synthesisui 0.16.141 → 0.16.145

package/dist/agent-wiring.js

@@ -1,5 +1,5 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 const HOOK_MATCHER = "Write|Edit|MultiEdit";
 const exists = (p) => access(p).then(() => true, () => false);
 async function readJson(path) {
@@ -67,13 +67,26 @@ async function wireHook(root, command) {
     await writeFile(path, `${JSON.stringify({ ...settings, hooks: { ...hooks, PostToolUse: post } }, null, 2)}\n`, "utf8");
     return { status: "added", command };
 }
-async function wireMcp(root, version) {
-    const path = join(root, ".mcp.json");
+/**
+ * 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
+ * (`mcpServers`). Então cobrir os dois é o mesmo JSON num segundo caminho, e as 11 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`.
+ */
+async function wireMcpAt(root, version, rel) {
+    const path = join(root, rel);
     const config = await readJson(path);
     const servers = (config.mcpServers ?? {});
     if (servers.synthesisui)
         return "already there";
     const local = await exists(join(root, "node_modules", ".bin", "synthesisui"));
+    await mkdir(dirname(path), { recursive: true }).catch(() => { });
     await writeFile(path, `${JSON.stringify({
         ...config,
         mcpServers: {
@@ -89,6 +102,23 @@ async function wireMcp(root, version) {
     }, null, 2)}\n`, "utf8");
     return "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.
+ */
+async function wireMcp(root, version) {
+    const wrote = [];
+    wrote.push({
+        path: ".mcp.json",
+        status: await wireMcpAt(root, version, ".mcp.json"),
+    });
+    if (await exists(join(root, ".cursor")))
+        wrote.push({
+            path: ".cursor/mcp.json",
+            status: await wireMcpAt(root, version, ".cursor/mcp.json"),
+        });
+    return wrote;
+}
 export async function wireAgent(root, version, want) {
     const proposed = await hookCommand(root, version);
     const hook = want.hook

package/dist/claude-md.js

@@ -1,5 +1,5 @@
-import { readdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { hasHook } from "./agent-wiring.js";
 const START = "<!-- synthesisui:start -->";
 const END = "<!-- synthesisui:end -->";
@@ -340,34 +340,84 @@ _Block managed by the CLI - do not edit by hand; run \`synthesisui ${onlyAdopted
  * DS. Idempotent: replaces the text between the markers if present, otherwise
  * creates the file / appends the block. Returns whether the file was created.
  */
+/**
+ * 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
+ * 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.
+ */
+const HOMES = [
+    { path: "CLAUDE.md" },
+    { path: "AGENTS.md" },
+    {
+        path: ".cursor/rules/synthesisui.mdc",
+        frontmatter: "---\ndescription: Design system rules - read before writing UI\nalwaysApply: true\n---\n\n",
+    },
+];
 export async function syncClaudeMd(projectRoot) {
     const installed = await readInstalled(projectRoot);
     const region = await renderRegion(projectRoot, installed);
-    const path = join(projectRoot, "CLAUDE.md");
-    let existing = null;
-    try {
-        existing = await readFile(path, "utf8");
-    }
-    catch {
-        existing = null;
-    }
-    if (existing === null) {
-        await writeFile(path, `${region}\n`, "utf8");
-        return { created: true, count: installed.length };
-    }
-    const startIdx = existing.indexOf(START);
-    const endIdx = existing.indexOf(END);
-    let next;
-    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-        next =
-            existing.slice(0, startIdx) +
-                region +
-                existing.slice(endIdx + END.length);
+    let createdAny = false;
+    for (const home of HOMES) {
+        const path = join(projectRoot, home.path);
+        let existing = null;
+        try {
+            existing = await readFile(path, "utf8");
+        }
+        catch {
+            existing = null;
+        }
+        /**
+         * O ARQUIVO NOVO SÓ NASCE PARA O CLAUDE.md.
+         *
+         * Criar `AGENTS.md` num repo que nunca teve um é decidir por outra pessoa qual agente ela usa, e
+         * um arquivo que apareceu sozinho na raiz é a primeira coisa que alguém apaga com raiva. Nos
+         * outros dois a regra é: se o arquivo existe, o bloco entra e se mantém atualizado; se não
+         * existe, não inventamos um.
+         */
+        if (existing === null) {
+            if (home.path !== "CLAUDE.md")
+                continue;
+            await mkdir(dirname(path), { recursive: true }).catch(() => { });
+            await writeFile(path, `${home.frontmatter ?? ""}${region}\n`, "utf8");
+            createdAny = true;
+            continue;
+        }
+        const startIdx = existing.indexOf(START);
+        const endIdx = existing.indexOf(END);
+        let next;
+        if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+            next =
+                existing.slice(0, startIdx) +
+                    region +
+                    existing.slice(endIdx + END.length);
+        }
+        else {
+            const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+            next = `${existing}${sep}${region}\n`;
+        }
+        if (next !== existing)
+            await writeFile(path, next, "utf8");
     }
-    else {
-        const sep = existing.endsWith("\n") ? "\n" : "\n\n";
-        next = `${existing}${sep}${region}\n`;
+    return { created: createdAny, count: installed.length };
+}
+/**
+ * Onde o bloco JÁ está, para o `connect` poder dizer isso em vez de ficar calado.
+ *
+ * Um repo com `AGENTS.md` e `.cursor/` ganhou governança nos três lugares e não tinha como saber -
+ * e o que não se diz não é adotado.
+ */
+export async function blockHomes(projectRoot) {
+    const found = [];
+    for (const home of HOMES) {
+        const raw = await readFile(join(projectRoot, home.path), "utf8").catch(() => null);
+        if (raw?.includes(START))
+            found.push(home.path);
     }
-    await writeFile(path, next, "utf8");
-    return { created: false, count: installed.length };
+    return found;
 }

package/dist/commands/ci.js

@@ -0,0 +1,84 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { body, paint, section, snippet } from "../output.js";
+/**
+ * `synthesisui ci` - a governança dentro do PR, em quatro linhas e sem Action nenhuma.
+ *
+ * A objeção que mata qualquer plataforma de governança é a terceira aba: se a checagem não está no
+ * PR, o engenheiro ignora. O doctor sempre pôde rodar em CI - offline, sem login, 1,8s sobre 2797
+ * arquivos - e ninguém ia descobrir isso lendo `--help`.
+ *
+ * O QUE ESTE COMANDO NÃO FAZ, e é a parte importante: ele não instala uma Action nossa. O GitHub lê
+ * `::warning file=…,line=…` do stdout de qualquer step, então a integração inteira é uma linha - e uma
+ * Action publicada seria uma peça a mais para manter oferecendo exactamente o mesmo. Menos superfície
+ * nossa no repo de outra pessoa é uma decisão de produto, não economia.
+ *
+ * E o workflow que ele imprime é uma CATRACA, nunca um portão: sem baseline nada reprova, com
+ * baseline reprova só a regressão. Um check que fica vermelho desde o primeiro dia é um check que
+ * alguém contorna na segunda semana - e aí o time cria a biblioteca paralela que o sistema existia
+ * para evitar.
+ */
+const WORKFLOW = `name: design system
+
+on: [pull_request]
+
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Annotations on the exact line of the diff. Nothing fails here.
+      - run: npx synthesisui@latest doctor --format=github
+      # The ratchet: fails ONLY when drift went up. With no baseline committed,
+      # this step says what to do and passes.
+      - run: npx synthesisui@latest doctor --baseline
+`;
+const PATH = ".github/workflows/design-system.yml";
+export async function ci(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    if (!opts.write) {
+        console.log(section("The design system in your pipeline"));
+        console.log(body("Two steps, no Action to install, no login, and nothing that fails on the debt you already have:"));
+        console.log("");
+        console.log(paint.dim(`  # ${PATH}`));
+        for (const line of WORKFLOW.split("\n"))
+            console.log(`  ${line}`);
+        console.log(section("The contract"));
+        console.log(body("--format=github    annotations on the exact line, always warnings"));
+        console.log(body("--format=sarif     for code-scanning or SonarQube, same findings"));
+        console.log(body("--baseline         exit 1 only when drift went UP, in total or in any file"));
+        console.log(body("--write-baseline   freeze where you are today, and commit it - yesterday's"));
+        console.log(body("                   debt stops hurting without going uncounted"));
+        console.log(body("--strict           exit 1 on ANY finding. Honest, and red on day one in a"));
+        console.log(body("                   repo with history. Prefer the baseline."));
+        console.log("");
+        console.log(body("Write it here, and the first baseline with it:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest ci --write"])));
+        return;
+    }
+    const file = join(root, PATH);
+    const before = await readFile(file, "utf8").catch(() => null);
+    if (before === WORKFLOW) {
+        console.log(section("CI"));
+        console.log(body(`${PATH} is already exactly this. Nothing to do.`));
+        return;
+    }
+    /**
+     * NUNCA SOBRESCREVE UM WORKFLOW EXISTENTE. Um arquivo de pipeline é território de outra pessoa, e
+     * "eu troquei o seu CI" é a última coisa que uma ferramenta de governança pode fazer e sobreviver.
+     */
+    if (before !== null) {
+        console.log(section("CI"));
+        console.log(body(`${PATH} already exists and is different, so nothing was written - a pipeline file is not ours to overwrite. Add the two steps by hand:`));
+        console.log("");
+        for (const line of WORKFLOW.split("\n").slice(6))
+            console.log(`  ${line}`);
+        return;
+    }
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, WORKFLOW, "utf8");
+    console.log(section("CI written"));
+    console.log(body(PATH));
+    console.log(body(paint.dim("Now freeze today's line so the first PR is not red for debt nobody in it wrote:")));
+    console.log(paint.blue(snippet(["npx synthesisui@latest doctor --write-baseline"])));
+}

package/dist/commands/connect.js

@@ -1,9 +1,11 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { wireAgent } from "../agent-wiring.js";
-import { syncClaudeMd } from "../claude-md.js";
-import { body, section, snippet } from "../output.js";
+import { blockHomes, syncClaudeMd } from "../claude-md.js";
+import { body, paint, section, snippet } from "../output.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
+import { INIT_SKILL, INIT_SKILL_PATH } from "../skill-init.js";
+import { ci } from "./ci.js";
 /**
  * `synthesisui connect` - put the three layers where they actually run.
  *
@@ -20,6 +22,11 @@ import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
  * not a default, and it deserves its own answer rather than riding along inside
  * a setup command.
  */
+/**
+ * Skills que a gente já distribuiu com outro nome. Uma linha por renomeação, para sempre - o repo de
+ * um cliente que rodou `connect` há um mês não sabe que o nome mudou.
+ */
+const LEGACY_SKILLS = ["import-design-system"];
 export async function connect(opts) {
     const root = opts.dir ?? process.cwd();
     // Both unless one is explicitly turned off - somebody who says `--no-hook`
@@ -36,12 +43,26 @@ export async function connect(opts) {
             : "· .claude/settings.json  already had it"));
         console.log(snippet([wired.command]));
     }
-    if (want.mcp) {
-        console.log(body(wired.mcp === "added"
-            ? "✓ .mcp.json              four tools, so the agent can ask instead of guess"
-            : "· .mcp.json              already had it"));
+    /**
+     * OS CAMINHOS DE MCP, POR NOME - e o número certo. Dizia "four tools" desde quando eram quatro; são
+     * 11, e um número velho na primeira tela é a coisa mais fácil de perder a confiança de alguém.
+     */
+    if (want.mcp && wired.mcp !== "skipped") {
+        for (const one of wired.mcp)
+            console.log(body(one.status === "added"
+                ? `✓ ${one.path.padEnd(22)} 11 tools, so the agent can ask instead of guess`
+                : `· ${one.path.padEnd(22)} already had it`));
     }
-    console.log(body("✓ CLAUDE.md              rewritten for what is installed"));
+    /**
+     * ONDE O BLOCO CAIU, DITO POR NOME.
+     *
+     * O mesmo bloco de regras é escrito em `CLAUDE.md`, e em `AGENTS.md` e `.cursor/rules/*.mdc`
+     * QUANDO ELES JÁ EXISTEM - criar um arquivo de agente que ninguém pediu é decidir por outra pessoa
+     * qual ferramenta ela usa. Dizer os nomes é o que faz um time descobrir que a governança já chegou
+     * no editor dele: até 05/08 ela só alcançava quem usa Claude Code, e ninguém tinha como saber.
+     */
+    for (const home of await blockHomes(root))
+        console.log(body(`✓ ${home.padEnd(22)} ${home === "CLAUDE.md" ? "rewritten for what is installed" : "the same rules, where this agent reads them"}`));
     /**
      * The fourth layer, and the one that had no installer at all: the import
      * skill existed only in our own repo, so the only way to get it was to clone
@@ -52,17 +73,70 @@ export async function connect(opts) {
      * already idempotent, and rerunning it is already the answer to "did
      * something change" - so nobody has to remember a second command.
      */
-    const skillPath = join(root, IMPORT_SKILL_PATH);
-    const before = await readFile(skillPath, "utf8").catch(() => null);
-    if (before !== IMPORT_SKILL) {
-        await mkdir(dirname(skillPath), { recursive: true });
-        await writeFile(skillPath, IMPORT_SKILL, "utf8");
+    /**
+     * AS DUAS SKILLS, e o `/sui-init` é a que importa mais aqui: é a PRIMEIRA CORRIDA, e uma skill que
+     * só aparece depois de reiniciar o editor não serve para a primeira corrida de ninguém. Ela vem no
+     * mesmo `connect` que ainda vai pedir o reinício - então quando a pessoa reabre, as duas existem.
+     */
+    const skills = [
+        {
+            path: INIT_SKILL_PATH,
+            source: INIT_SKILL,
+            label: "/sui-init",
+            what: "the first run, start to finish",
+        },
+        {
+            path: IMPORT_SKILL_PATH,
+            source: IMPORT_SKILL,
+            label: "/sui-import-ds",
+            what: "the import, orchestrated",
+        },
+    ];
+    /**
+     * A PASTA VELHA SAI, e isto é obrigatório numa renomeação de skill distribuída.
+     *
+     * O nome decide o CAMINHO, então renomear `import-design-system` para `sui-import-ds` sem apagar o
+     * antigo deixa, no repo de um cliente, uma cópia de um pipeline que não existe mais - e o agente
+     * dele tem duas skills descrevendo esteiras diferentes, sem jeito de saber qual é a viva. É a mesma
+     * falha que o spec do gêmeo existe para impedir, entrando pela porta de trás.
+     *
+     * `rm -rf` de um caminho NOSSO e nada além: a pasta é escrita por este comando, o conteúdo é o
+     * nosso texto, e ninguém edita uma skill gerada esperando que ela sobreviva a um `connect`.
+     */
+    for (const legacy of LEGACY_SKILLS) {
+        const dir = join(root, ".claude", "skills", legacy);
+        const had = await readFile(join(dir, "SKILL.md"), "utf8").catch(() => null);
+        if (had == null)
+            continue;
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+        console.log(body(`✕ /${legacy.padEnd(21)} removed - renamed to /sui-import-ds`));
+    }
+    for (const skill of skills) {
+        const skillPath = join(root, skill.path);
+        const before = await readFile(skillPath, "utf8").catch(() => null);
+        if (before !== skill.source) {
+            await mkdir(dirname(skillPath), { recursive: true });
+            await writeFile(skillPath, skill.source, "utf8");
+        }
+        console.log(body(before === skill.source
+            ? `· ${skill.label.padEnd(22)} already current`
+            : before == null
+                ? `✓ ${skill.label.padEnd(22)} ${skill.what}`
+                : `✓ ${skill.label.padEnd(22)} updated to this CLI's pipeline`));
+    }
+    /**
+     * O CI: escrito só quando pedido, e OFERECIDO sempre - com o que ele faz em duas linhas, porque
+     * "adicione CI" sem dizer que nada reprova dívida herdada não é uma oferta, é um risco.
+     */
+    if (opts.ci) {
+        console.log("");
+        await ci({ dir: root, write: true });
+    }
+    else {
+        console.log("");
+        console.log(body(paint.dim("Your PRs can carry this too: annotations on the exact line, and a ratchet that fails only when drift goes UP - never on the debt you already have.")));
+        console.log(paint.blue(snippet(["npx synthesisui@latest ci"])));
     }
-    console.log(body(before === IMPORT_SKILL
-        ? "· /import-design-system  already current"
-        : before == null
-            ? "✓ /import-design-system  the import, orchestrated"
-            : "✓ /import-design-system  updated to this CLI's pipeline"));
     // The step that cost a round trip the first time this was tried by hand,
     // and would cost every single person one.
     console.log("");

package/dist/commands/doctor.js

@@ -1,5 +1,7 @@
-import { readdir, readFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { describeFix, planFix, readerFor, writeFix, } from "../doctor/apply-fix.js";
+import { baselineOf, compareToBaseline, describeVerdict, githubAnnotations, sarifOf, } from "../doctor/ci-format.js";
 import { findDivergences } from "../doctor/coherence.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { checkContracts } from "../doctor/contract-check.js";
@@ -52,6 +54,25 @@ const SKIP = new Set([
     ".vercel",
     // Our own installed artifacts are the answer, not the problem.
     "_synthesisui",
+    /**
+     * SAÍDA DE GERADOR, e cada nome aqui foi medido num repo real antes de entrar.
+     *
+     * `_build` é o do Sphinx, e no repo do dono ele carrega 10 arquivos de UI - o CSS do tema
+     * `alabaster`, com a paleta do TEMA e não a dele. Medido em 05/08: as 200 anotações do formato de
+     * CI saíram TODAS de lá, então o teto foi consumido inteiro por um diretório que ninguém edita e
+     * nenhum achado de verdade chegou ao PR. Anotar arquivo gerado é o jeito mais rápido de alguém
+     * silenciar a ferramenta.
+     */
+    "_build",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "vendor",
+    ".output",
+    ".svelte-kit",
+    ".cache",
+    ".parcel-cache",
+    ".nuxt",
 ]);
 export async function* walk(dir, 
 /** Filled with nested projects that were SKIPPED - each speaks its own
@@ -387,6 +408,8 @@ async function readWiring(root, slug) {
     }
     return w;
 }
+/** Onde o retrato mora por default: dentro do que a esteira já escreve, e commitável. */
+const DEFAULT_BASELINE = "_synthesisui/drift-baseline.json";
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
     const scopes = (opts.scopes ?? []).map((s) => resolve(root, s));
@@ -470,6 +493,26 @@ export async function doctor(opts) {
     }
     const breaches = checkContracts(tallyToInventory(tally, 400), documents);
     const d = diagnose(reports);
+    /**
+     * A SAÍDA DE MÁQUINA SAI AQUI, E SOZINHA.
+     *
+     * Antes de qualquer linha humana: um log de CI com as duas coisas é um log que ninguém lê, e um
+     * SARIF com um cabeçalho bonito no meio não parseia. As anotações do GitHub não precisam de Action
+     * nenhuma - ele lê `::warning` do stdout de qualquer step, então a integração é uma linha no
+     * workflow deles.
+     *
+     * E NÃO REPROVA: quem decide o exit code é a catraca, mais abaixo. Anotação em cima de dívida
+     * herdada é informação; reprovar por ela é o pedágio que faz um time criar biblioteca paralela.
+     */
+    if (opts.format === "github") {
+        for (const line of githubAnnotations(d))
+            console.log(line);
+        return;
+    }
+    if (opts.format === "sarif") {
+        console.log(sarifOf(d, opts.cli));
+        return;
+    }
     // Nine releases in one evening added a section each, every one justified on
     // its own, and nobody read the whole. The result was 151 lines carrying about
     // eight lines of meaning. Detail is now something you ask for.
@@ -1212,6 +1255,67 @@ export async function doctor(opts) {
         }
         console.log("");
     }
+    /**
+     * A CATRACA, e ela vem ANTES do `--strict` de propósito.
+     *
+     * `--strict` reprova por qualquer achado, o que num repo legado é vermelho no dia um e um portão
+     * vermelho para sempre é um portão que alguém contorna. Com um baseline, o que reprova é a
+     * REGRESSÃO - e aí a dívida de ontem para de doer sem deixar de ser contada.
+     */
+    /**
+     * O CONSERTO, ANTES DE QUALQUER RELATÓRIO - ver `apply-fix.ts`.
+     *
+     * Sai aqui porque quem pediu `--fix` quer o resultado da edição, não o diagnóstico de novo: imprimir
+     * 1500 achados e depois dizer "troquei 900" é fazer a pessoa procurar a linha que importa.
+     */
+    if (opts.fix) {
+        const read = await readerFor(root, d.findings.filter((f) => f.token).map((f) => f.file));
+        const { result, next } = planFix(d, read);
+        if (!opts.dry)
+            await writeFix(root, next);
+        console.log(section(opts.dry ? "What --fix would do" : "Fixed what had an answer"));
+        for (const line of describeFix(result, opts.dry === true))
+            console.log(body(line));
+        if (!opts.dry && result.applied.length > 0) {
+            console.log("");
+            console.log(body(paint.dim("Read the diff before committing - it is your code, and this replaced literals with the tokens your own system declares.")));
+        }
+        return;
+    }
+    if (opts.writeBaseline) {
+        const path = resolve(root, opts.baseline ?? DEFAULT_BASELINE);
+        await mkdir(dirname(path), { recursive: true }).catch(() => { });
+        await writeFile(path, `${JSON.stringify(baselineOf(d, {
+            at: new Date().toISOString(),
+            ...(opts.cli ? { cli: opts.cli } : {}),
+            ...(opts.scopes?.length ? { scope: opts.scopes.join(",") } : {}),
+        }), null, 1)}\n`, "utf8");
+        console.log(section("Baseline written"));
+        console.log(body(`${d.findings.length} findings and ${d.phantomUses} phantom uses are now the line to hold. A run that goes above it fails; everything at or below it passes.`));
+        console.log(body(paint.dim(relative(root, path))));
+        return;
+    }
+    if (opts.baseline || opts.compareBaseline) {
+        const path = resolve(root, opts.baseline ?? DEFAULT_BASELINE);
+        const raw = await readFile(path, "utf8").catch(() => null);
+        const base = raw
+            ? JSON.parse(raw)
+            : null;
+        if (!base?.baseline) {
+            console.log(section("Baseline"));
+            console.log(body(`No readable baseline at ${relative(root, path)}. Write one first: npx synthesisui doctor --write-baseline`));
+            return;
+        }
+        const verdict = compareToBaseline(d, base, {
+            ...(opts.scopes?.length ? { scope: opts.scopes.join(",") } : {}),
+        });
+        console.log(section(verdict.worse ? "Drift went up" : "Ratchet"));
+        for (const line of describeVerdict(verdict))
+            console.log(body(line));
+        if (verdict.worse)
+            process.exitCode = 1;
+        return;
+    }
     if (opts.strict) {
         const mine = d.findings.length > 0 || overrides.length > 0;
         // The two system lenses are deliberately NOT in here by default. A team