synthesisui 0.16.499 → 0.16.501

package/dist/commands/read.js

@@ -0,0 +1,355 @@
+import { execFileSync } from "node:child_process";
+import { desligarCaptura, ligarCaptura } from "../transcript.js";
+import { adopt } from "./adopt.js";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join, relative } from "node:path";
+import { classify, pixelRatio } from "../reading/classify.js";
+import { PAGE_SCRIPT } from "../reading/page-script.js";
+import { decodePng } from "../reading/png.js";
+import { moduleClassName, pxOf } from "../role-rules.js";
+import { agentsToMaintain } from "../agents-chosen.js";
+import { syncClaudeMd } from "../claude-md.js";
+import { projectRootFrom } from "./hook.js";
+/**
+ * `synthesisui read` - O QUE A SUA PÁGINA JÁ DECIDIU (jornada "a leitura no agente", E02, 18/10).
+ *
+ * A fase 1 do mapa aprovado: depois da primeira tela que a camada de estética criou, a pessoa pede ao agente para ler a
+ * página, e recebe o sistema que ela já decidiu - os papéis de título com a classe e o lugar no código, as escalas, as
+ * quebras que a fazem ser dela, a deriva e o contraste que falha. Lê a página RENDERIZADA no dev server (o que o visitante
+ * vê) e liga cada achado ao componente pelo React, não pela forma de estilo.
+ *
+ * O NAVEGADOR É SOB DEMANDA (D9 do mapa): o CLI continua sem dependência nenhuma. No primeiro `read` ele DIZ o que vai
+ * baixar e baixa o leitor (playwright-core) numa pasta própria; usa o Chromium que já estiver na máquina, e só baixa um
+ * quando não há nenhum.
+ *
+ * Grava `_synthesisui/reading.json` - a proposta. O `rules.json` nasce da confirmação da pessoa (E03), nunca daqui.
+ */
+const READER_VERSION = "1.58.2";
+const READER_DIR = join(homedir(), ".synthesisui", "reader");
+const VIEWPORTS = [
+    ["desktop", 1440, 900],
+    ["celular", 390, 844],
+];
+function loadReader(say) {
+    const override = process.env.SYNTHESISUI_PLAYWRIGHT;
+    if (override)
+        return createRequire(join(override, "package.json"))(override);
+    const mod = join(READER_DIR, "node_modules", "playwright-core");
+    if (!existsSync(mod)) {
+        say(`First read on this machine: downloading the page reader (playwright-core ${READER_VERSION}, about 3 MB) into ${READER_DIR}. It is used only by \`read\`.`);
+        mkdirSync(READER_DIR, { recursive: true });
+        execFileSync("npm", ["install", "--prefix", READER_DIR, "--no-save", "--no-audit", "--no-fund", `playwright-core@${READER_VERSION}`], { stdio: "ignore" });
+    }
+    return createRequire(join(READER_DIR, "package.json"))("playwright-core");
+}
+async function launch(pw, say) {
+    for (const o of [{}, { channel: "chrome" }, { channel: "msedge" }]) {
+        try {
+            return await pw.chromium.launch(o);
+        }
+        catch {
+            /* o próximo */
+        }
+    }
+    say("No Chromium found on this machine: downloading one for the reader (about 150 MB, once).");
+    execFileSync(process.execPath, [join(READER_DIR, "node_modules", "playwright-core", "cli.js"), "install", "chromium"], { stdio: "ignore" });
+    return pw.chromium.launch();
+}
+/**
+ * O DEV SERVER DESTE PROJETO, E NÃO O PRIMEIRO QUE RESPONDER - a porta que o script `dev` do próprio projeto declara
+ * (`-p 3389`, `--port 3389`, `PORT=3389`) vem antes das portas de sempre. Sem isto, numa máquina com outro projeto na
+ * 3000, a leitura descreveria a página de outra pessoa.
+ */
+function declaredPort(root) {
+    try {
+        const dev = (JSON.parse(readFileSync(join(root, "package.json"), "utf8")).scripts?.dev ?? "");
+        const m = dev.match(/(?:-p|--port)[ =](\d{2,5})|PORT=(\d{2,5})/);
+        return m ? Number(m[1] ?? m[2]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function findServer(url, root) {
+    const port = declaredPort(root);
+    const cands = url ? [url] : [...(port ? [`http://localhost:${port}`] : []), "http://localhost:3000", "http://localhost:3001", "http://localhost:5173", "http://localhost:4321"];
+    for (const u of cands) {
+        try {
+            const r = await fetch(u, { signal: AbortSignal.timeout(4000) });
+            if (r.status < 500)
+                return u;
+        }
+        catch {
+            /* o próximo */
+        }
+    }
+    return null;
+}
+/** O maior tamanho entre as classes de um texto (o do desktop), sem o prefixo de tela - a mesma escolha da checagem. */
+function sizeClassOf(cls) {
+    const toks = cls.match(/(?:[a-z0-9]+:)?text-(?:\[(?:clamp\([^\]\s]+\)|[\d.]+(?:rem|px|em))\]|xs|sm|base|lg|[2-9]?xl)(?=\s|$|\|)/g) ?? [];
+    if (toks.length === 0)
+        return null;
+    const best = toks.sort((a, b) => (pxOf(b) ?? 0) - (pxOf(a) ?? 0))[0];
+    return best.replace(/^(?:[a-z0-9]+:)+/, "");
+}
+function sources(root) {
+    const out = [];
+    const walk = (d) => {
+        for (const n of readdirSync(d)) {
+            if (n === "node_modules" || n.startsWith(".") || n === "_synthesisui")
+                continue;
+            const p = join(d, n);
+            const s = statSync(p);
+            if (s.isDirectory())
+                walk(p);
+            else if (/\.(tsx|jsx)$/.test(n))
+                out.push(p);
+        }
+    };
+    const src = existsSync(join(root, "src")) ? join(root, "src") : root;
+    walk(src);
+    return out;
+}
+/** Onde o texto mora no código: o componente (React) -> o arquivo que o declara -> a linha da classe; senão, pela classe. */
+/**
+ * A CLASSE DE UM CSS MODULE NO DOM - `page-module___8aEwW__h2` (o Turbopack: arquivo, hash, nome local). Achado na rodada
+ * real da porta (18/10): sem isto, a página que o impeccable escreveu com `styles.h2` saía com 5 papéis lidos e 0
+ * gravados. A extensão vem do import que o código escreve.
+ */
+function moduleOf(cls, files) {
+    /* a do próprio elemento primeiro; sem ela, a do título e a do pai (a capa da porta-2: `<span>` sem classe dentro de
+       `<p className={styles.batch}>`, com o tamanho em `.batch span`) */
+    for (const tok of cls.split(" | ").flatMap((part) => part.split(/\s+/))) {
+        const m = tok.match(/^([A-Za-z0-9-]+?)-module__.+?__([A-Za-z0-9_-]+)$/);
+        if (!m)
+            continue;
+        const stem = m[1];
+        const local = m[2];
+        const imp = new RegExp(`["'][^"']*\\b${stem}\\.module\\.(s?css)["']`);
+        const ext = files.map((f) => readFileSync(f, "utf8").match(imp)?.[1]).find(Boolean) ?? "css";
+        return { name: moduleClassName(`${stem}.module.${ext}`, local), local };
+    }
+    return null;
+}
+function homeOf(root, files, t) {
+    const mod = sizeClassOf(t.cls) ? null : moduleOf(t.cls, files);
+    const cls = sizeClassOf(t.cls) ?? mod?.name ?? null;
+    const lineOf = (f) => {
+        if (!cls)
+            return null;
+        const lines = readFileSync(f, "utf8").split("\n");
+        const i = mod
+            ? lines.findIndex((l) => new RegExp(`\\b\\w+(?:\\.${mod.local}\\b|\\[["']${mod.local}["']\\])`).test(l))
+            : lines.findIndex((l) => l.includes(cls));
+        return i >= 0 ? i + 1 : null;
+    };
+    if (t.comp) {
+        const decl = new RegExp(`(function|const|class)\\s+${t.comp}\\b`);
+        const f = files.find((x) => decl.test(readFileSync(x, "utf8")));
+        if (f)
+            return { file: relative(root, f), line: lineOf(f), cls, via: "component", component: t.comp };
+    }
+    if (cls && !mod) {
+        const f = files.find((x) => readFileSync(x, "utf8").includes(cls));
+        if (f)
+            return { file: relative(root, f), line: lineOf(f), cls, via: "class", component: t.comp };
+    }
+    return null;
+}
+/**
+ * NO MÁXIMO OITO PERGUNTAS, UMA DECISÃO CADA - por quebra e por papel com deriva, nunca por elemento (seção 6 do estudo:
+ * "5-8 perguntas por projeto, não 300"). As quebras vêm primeiro: dizer sim à própria assinatura é o caminho feliz. A
+ * primeira opção é sempre a padrão, e é o que vale quando a pessoa não responde.
+ */
+/** O nome que a pessoa entende - nunca o rótulo interno da classificação ("h3 de cartão", "número"). */
+function plainRole(role) {
+    if (role === "número")
+        return "big number";
+    if (role === "decoração")
+        return "decoration";
+    if (role === "bloco")
+        return "block";
+    return nameOf(role);
+}
+function questionsFor(breaks, drift) {
+    const qs = breaks.map((b) => ({
+        id: `break:${b.rule}:${b.role}:${b.px}`,
+        text: `Is this on purpose? The ${plainRole(b.role)} ${b.rule === "Q2" ? "is tilted off the grid" : b.rule === "Q3" ? "is a big motif, outside the headings" : "goes above the heading scale"} (${b.what}).`,
+        options: ["Yes, it is part of my design", "No, make it follow the scale"],
+    }));
+    const groups = new Map();
+    for (const d of drift) {
+        const g = groups.get(`${d.role}|${d.surface}`) ?? { role: d.role, surface: d.surface, rulePx: d.rulePx, pxs: [] };
+        g.pxs.push(d.px);
+        groups.set(`${d.role}|${d.surface}`, g);
+    }
+    for (const g of groups.values())
+        qs.push({
+            id: `drift:${g.role}:${g.surface}`,
+            text: `Are these the same ${plainRole(g.role)}? Most places use ${g.rulePx}px; here ${g.pxs.join("px, ")}px.`,
+            options: [`Yes, use ${g.rulePx}px everywhere`, "No, they are different roles"],
+        });
+    return qs.slice(0, 8);
+}
+const contextOf = (role) => (role.includes("cartão") ? "card" : role.includes("texto corrido") ? "prose" : "section");
+const NAME = { h1: "cover title", h2: "section title", h3: "subheading" };
+const nameOf = (role) => {
+    const el = role.split(" ")[0];
+    return contextOf(role) === "card" ? "card title" : contextOf(role) === "prose" ? `heading inside running text (${el})` : (NAME[el] ?? role);
+};
+const at = (h) => (h ? `${h.file}${h.line ? `:${h.line}` : ""}` : "");
+/**
+ * \`read --confirm\` - AS RESPOSTAS DELA VIRAM O SISTEMA (E03). Lê \`reading.json\` e as respostas (um JSON \`{ "<id da
+ * pergunta>": 0 | 1 }\`, o índice da opção; sem arquivo, a primeira opção de todas) e grava \`_synthesisui/ds/<slug>/rules.json\`
+ * no formato que a checagem lê (\`role-rules.ts\`); depois regenera o contrato. Um "não" numa quebra a tira do sistema; um
+ * "são papéis diferentes" vira papel próprio, com a classe que ele usa.
+ */
+export async function confirm(opts) {
+    const say = (s) => process.stdout.write(`${s}\n`);
+    const root = opts.dir ?? projectRootFrom(process.cwd());
+    const rp = join(root, "_synthesisui", "reading.json");
+    if (!existsSync(rp)) {
+        say("No reading yet - run `synthesisui read` first.");
+        process.exitCode = 1;
+        return;
+    }
+    const R = JSON.parse(readFileSync(rp, "utf8"));
+    const answers = opts.answers ? JSON.parse(readFileSync(opts.answers, "utf8")) : {};
+    const pick = (id) => answers[id] ?? 0;
+    const dsDir = join(root, "_synthesisui", "ds");
+    const firstSystem = () => existsSync(dsDir) ? readdirSync(dsDir).find((d) => statSync(join(dsDir, d)).isDirectory()) : undefined;
+    /* O SISTEMA NASCE AQUI quando o projeto chegou pela porta (fase 2, 18/10): o `init` não adota, porque num projeto vazio
+       os únicos tokens são os de exemplo do create-next-app. Agora a página já decidiu - os tokens que ela tem são os dela. */
+    if (!firstSystem()) {
+        ligarCaptura();
+        try {
+            await adopt({ dir: root, write: true });
+        }
+        finally {
+            desligarCaptura();
+        }
+    }
+    const slug = firstSystem();
+    if (!slug) {
+        say("No tokens found in this project's CSS, so there is no system to write the answers into - check that the page's stylesheet declares them in :root or @theme.");
+        process.exitCode = 1;
+        return;
+    }
+    const roles = R.roles
+        .filter((r) => r.home?.cls)
+        .map((r) => ({
+        id: `${r.role.split(" ")[0]}-${contextOf(r.role)}-${r.surface}`, name: nameOf(r.role), element: r.role.split(" ")[0],
+        context: contextOf(r.role), surface: r.surface, class: r.home?.cls, px: r.px, home: at(r.home), places: r.places,
+    }));
+    for (const d of R.drift) {
+        if (pick(`drift:${d.role}:${d.surface}`) !== 1 || !d.home?.cls)
+            continue;
+        roles.push({ id: `${d.role.split(" ")[0]}-${contextOf(d.role)}-${d.surface}-${d.px}`, name: `${nameOf(d.role)} (${d.px}px)`, element: d.role.split(" ")[0],
+            context: contextOf(d.role), surface: d.surface, class: d.home.cls, px: d.px, home: at(d.home), places: 1 });
+    }
+    const breaks = R.breaks
+        .filter((b) => pick(`break:${b.rule}:${b.role}:${b.px}`) === 0 && b.home)
+        .map((b) => ({ id: `${b.rule}-${b.px}`, rule: b.name, what: b.what, element: b.role, class: b.home?.cls ?? null, px: b.px,
+        /* o ARQUIVO onde a quebra mora, como a checagem compara (role-rules.ts) - não o componente do React, que pode
+           ser um de vários no mesmo arquivo (o DogCard mora em Entries.tsx) */
+        allowedIn: (b.home?.file.split("/").pop()?.replace(/\.[jt]sx?$/, "") ?? ""), home: at(b.home) }));
+    const rules = { version: 1, enforce: true, source: `synthesisui read, ${R.read}`, confirmed: opts.answers ? "the person's answers" : "yes to every question (no answers file)", roles, breaks };
+    writeFileSync(join(dsDir, slug, "rules.json"), `${JSON.stringify(rules, null, 2)}\n`);
+    const contract = await syncClaudeMd(root, await agentsToMaintain(root));
+    say(`Your system: ${roles.length} roles and ${breaks.length} breaks, written to _synthesisui/ds/${slug}/rules.json.`);
+    say(contract ? "The contract your agent reads now lists them - every heading is checked against its role at the end of each turn." : "Run `synthesisui connect` so your agent reads and checks it.");
+}
+export async function read(opts) {
+    const say = (s) => process.stdout.write(`${s}\n`);
+    const root = opts.dir ?? projectRootFrom(process.cwd());
+    const started = Date.now();
+    const base = await findServer(opts.url, root);
+    if (!base) {
+        say("No dev server answered (tried :3000, :3001, :5173, :4321). Start it - `npm run dev` - and run `synthesisui read` again, or pass `--url`.");
+        process.exitCode = 1;
+        return;
+    }
+    const routes = opts.routes?.length ? opts.routes : ["/"];
+    const pw = loadReader(say);
+    const browser = await launch(pw, say);
+    const seen = [];
+    const pages = new Map();
+    try {
+        for (const rota of routes) {
+            for (const [disp, w, h] of VIEWPORTS) {
+                const ctx = await browser.newContext({ viewport: { width: w, height: h }, reducedMotion: "reduce" });
+                const page = await ctx.newPage();
+                await page.goto(new URL(rota, base).href, { waitUntil: "networkidle", timeout: 90_000 });
+                await page.waitForTimeout(800);
+                const textos = (await page.evaluate(PAGE_SCRIPT));
+                for (const t of textos)
+                    seen.push({ ...t, rota, disp });
+                pages.set(`${rota}|${disp}`, { page, ctx });
+            }
+        }
+        const reading = classify(seen);
+        // cada contraste baixo conferido pelos pixels: sem tinta é texto não pintado; acima do alvo, o DOM errou o fundo
+        const confirmed = [];
+        for (const f of reading.contraste) {
+            const p = pages.get(`${f.sample.rota}|${f.sample.disp}`);
+            let px = null;
+            if (p && f.sample.w >= 2 && f.sample.h >= 2) {
+                const png = await p.page.screenshot({ fullPage: true, clip: { x: Math.max(0, f.sample.x), y: Math.max(0, f.sample.y), width: f.sample.w, height: f.sample.h } }).catch(() => null);
+                const rgba = png ? decodePng(png) : null;
+                px = rgba ? pixelRatio(rgba) : null;
+            }
+            if (px !== null && (px < 1.2 || px >= f.alvo))
+                continue;
+            confirmed.push({ ...f, pixels: px });
+        }
+        reading.contraste = confirmed;
+        const files = sources(root);
+        const home = (t) => homeOf(root, files, t);
+        const out = {
+            read: new Date().toISOString(),
+            url: base,
+            routes,
+            seconds: Math.round((Date.now() - started) / 1000),
+            sectionTitlePx: reading.tituloSecao,
+            typeSteps: reading.passos,
+            roles: reading.papeis.map((r) => ({ role: r.papel, surface: r.superficie, px: r.px, places: r.lugares, seen: r.onde, home: home(r.sample) })),
+            breaks: reading.quebras.map((q) => ({ rule: q.regra, name: q.nome, role: q.papel, px: q.px, what: q.medida, times: q.vezes, seen: q.onde, home: home(q.sample) })),
+            drift: reading.deriva.map((d) => ({ role: d.papel, surface: d.superficie, px: d.px, rulePx: d.regraPx, seen: d.onde, home: home(d.sample), ruleHome: home(d.ruleSample) })),
+            lowContrast: reading.contraste.map((c) => ({ ratio: c.razao, target: c.alvo, text: c.texto, background: c.fundo, px: c.px, seen: c.onde, home: home(c.sample) })),
+            overImages: reading.sobreImagem,
+            questions: [],
+        };
+        out.questions = questionsFor(out.breaks, out.drift);
+        mkdirSync(join(root, "_synthesisui"), { recursive: true });
+        writeFileSync(join(root, "_synthesisui", "reading.json"), `${JSON.stringify(out, null, 2)}\n`);
+        const at = (x) => (x ? `${x.file}${x.line ? `:${x.line}` : ""}` : "?");
+        say(`\nWhat your page already decided (${routes.join(", ")}, read in ${out.seconds}s):\n`);
+        say(`  Type steps that repeat: ${out.typeSteps.join(" · ")} px`);
+        say("  Roles:");
+        for (const r of out.roles)
+            say(`    ${r.role} (${r.surface}): ${r.px}px, ${r.home?.cls ?? "?"} - ${at(r.home)}`);
+        if (out.breaks.length)
+            say("  Breaks (each one rule, broken on purpose - confirm or not):");
+        for (const q of out.breaks)
+            say(`    ${q.name}: ${q.role}, ${q.what} - ${at(q.home)}`);
+        if (out.drift.length)
+            say("  Drift (the same role at another size):");
+        for (const d of out.drift)
+            say(`    ${d.role} at ${d.px}px instead of ${d.rulePx}px - ${at(d.home)}`);
+        if (out.lowContrast.length)
+            say("  Hard to read (checked against the pixels):");
+        for (const c of out.lowContrast)
+            say(`    ${c.ratio}:1 (needs ${c.target}:1) ${c.text} on ${c.background} - ${at(c.home)}`);
+        if (out.questions.length)
+            say(`\n  ${out.questions.length} question${out.questions.length === 1 ? "" : "s"} for the person in _synthesisui/reading.json - then \`synthesisui read --confirm <answers.json>\` (no file = yes to all).`);
+        say(`\n  Written to _synthesisui/reading.json. Nothing in your code changed.`);
+    }
+    finally {
+        for (const { ctx } of pages.values())
+            await ctx.close().catch(() => { });
+        await browser.close().catch(() => { });
+    }
+}

package/dist/door.js

@@ -0,0 +1,176 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { connect } from "./commands/connect.js";
+import { MCP_TOOL_COUNT } from "./commands/mcp.js";
+import { body, paint, section, snippet } from "./output.js";
+import { SKILLS } from "./skills.js";
+import { desligarCaptura, ligarCaptura } from "./transcript.js";
+/**
+ * A CAMADA DE ESTÉTICA PADRÃO, na versão que a régua do conjunto provou (18/10: corte, linhas A-C, relógios). O impeccable
+ * muda rápido; subir este número pede a régua de novo (D10 do mapa), não só o publish dele.
+ */
+export const IMPECCABLE_VERSION = "4.6.0";
+/** O impeccable que já está no projeto, pela skill que o instalador DELE escreve - nunca por um arquivo nosso. */
+export function impeccableIn(root) {
+    const skill = join(root, ".claude", "skills", "impeccable", "SKILL.md");
+    if (!existsSync(skill))
+        return null;
+    try {
+        const head = readFileSync(skill, "utf8").slice(0, 4000);
+        return /^version:\s*(\S+)/m.exec(head)?.[1] ?? "?";
+    }
+    catch {
+        return "?";
+    }
+}
+/** Uma pergunta, o sim como padrão - e só num terminal de verdade. */
+async function askAesthetic() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`  Add the aesthetic layer - impeccable ${IMPECCABLE_VERSION}, by its own installer? It creates the first look; SynthesisUI keeps every screen after it consistent. [Y/n] `);
+        return !/^n/i.test(answer.trim());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * COMPOR, NUNCA FORKAR (decisão dele, 18/10 15:25): o SynthesisUI é o ecossistema e o impeccable é uma camada. Quem
+ * instala é o instalador DELE, chamado por nós; nenhum arquivo dele é escrito, copiado ou apagado aqui. Já instalado,
+ * fica como está.
+ */
+async function aestheticLayer(root, wanted) {
+    const found = impeccableIn(root);
+    if (found)
+        return { kind: "found", version: found };
+    if (wanted === "none")
+        return { kind: "declined", asked: false };
+    if (wanted !== "impeccable") {
+        const yes = await askAesthetic();
+        if (yes === false)
+            return { kind: "declined", asked: true };
+    }
+    try {
+        execFileSync("npx", ["-y", `impeccable@${IMPECCABLE_VERSION}`, "install", "-y", "--providers=claude", "--project"], { cwd: root, stdio: "pipe" });
+        return { kind: "installed", version: impeccableIn(root) ?? IMPECCABLE_VERSION };
+    }
+    catch (e) {
+        const err = e;
+        return {
+            kind: "failed",
+            why: err.stderr?.toString().trim().split("\n").filter(Boolean).pop() ??
+                err.message ??
+                "unknown",
+        };
+    }
+}
+/** O gerenciador que o projeto já usa, pelo lockfile - instalar com outro deixaria dois lockfiles brigando. */
+export function packageManagerOf(root) {
+    if (existsSync(join(root, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(root, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+        return "bun";
+    return "npm";
+}
+export function addDevArgs(pm, spec) {
+    if (pm === "npm")
+        return ["install", "--save-dev", "--no-audit", "--no-fund", spec];
+    if (pm === "bun")
+        return ["add", "--dev", spec];
+    return ["add", "--save-dev", spec];
+}
+/**
+ * O CLI COMO DEPENDÊNCIA DO PROJETO - é o que faz o fim do turno rodar a versão dele, e ~10x mais rápido que o `npx`
+ * (medido em 27/07, ver `hookCommand`). O `connect` escolhe sozinho o local quando ele está em `node_modules`, então
+ * esta instalação vem ANTES dele.
+ *
+ * `spec` existe para provar uma versão antes do publish (um tarball do `npm pack`); o padrão é a versão que roda.
+ */
+async function installLocalCli(root, spec) {
+    const pm = packageManagerOf(root);
+    try {
+        execFileSync(pm, addDevArgs(pm, spec), { cwd: root, stdio: "pipe" });
+        return { ok: true, pm };
+    }
+    catch (e) {
+        const err = e;
+        const why = err.stderr?.toString().trim().split("\n").filter(Boolean).pop() ??
+            err.message ??
+            "unknown";
+        return { ok: false, pm, why };
+    }
+}
+export async function openTheDoor(opts) {
+    const { root, version } = opts;
+    const pkgPath = join(root, "package.json");
+    const hasPackage = existsSync(pkgPath);
+    const local = hasPackage
+        ? await installLocalCli(root, opts.pkg ?? `synthesisui@${version}`)
+        : null;
+    const layer = await aestheticLayer(root, opts.aesthetic);
+    ligarCaptura();
+    let failed = null;
+    try {
+        await connect({
+            dir: root,
+            version,
+            ...(opts.registry ? { registry: opts.registry } : {}),
+            hook: true,
+            mcp: true,
+            agents: "claude",
+            interactive: false,
+        });
+    }
+    catch (e) {
+        failed = e;
+    }
+    const connectLines = desligarCaptura();
+    if (failed) {
+        for (const line of [...opts.configLines, ...connectLines])
+            console.log(line);
+        throw failed;
+    }
+    const installed = hasPackage
+        ? (JSON.parse(await readFile(pkgPath, "utf8")).devDependencies?.synthesisui ?? null)
+        : null;
+    console.log(section("SynthesisUI is set up"));
+    console.log("");
+    console.log(body(local?.ok
+        ? `✓ the CLI       synthesisui ${version} in your devDependencies (${local.pm}) - the check runs this one`
+        : local
+            ? `· the CLI       not installed (${local.why}) - the check runs it through npx, slower`
+            : "· the CLI       no package.json here - the check runs it through npx, slower"));
+    console.log(body(`✓ your agent    Claude Code: the check at the end of each turn, ${MCP_TOOL_COUNT} tools, ${SKILLS.length} skills`));
+    console.log(body(layer.kind === "found"
+        ? `✓ aesthetic     impeccable ${layer.version} was already here - left exactly as it is`
+        : layer.kind === "installed"
+            ? `✓ aesthetic     impeccable ${layer.version}, by its own installer - it creates the first look`
+            : layer.kind === "failed"
+                ? `· aesthetic     impeccable did not install (${layer.why}) - run init again to retry`
+                : "· aesthetic     none - the first look comes from your agent alone, with no design direction behind it"));
+    if (layer.kind === "declined")
+        console.log(body(paint.faint("                add it later: npx synthesisui init --aesthetic impeccable")));
+    if (layer.kind === "installed" && opts.aesthetic !== "impeccable" && !process.stdin.isTTY)
+        console.log(body(paint.faint("                installed by default - `--aesthetic none` leaves it out")));
+    console.log(body("✓ no account    nothing here needs one"));
+    if (installed && local?.ok === false)
+        console.log(body(paint.faint(`  (package.json already lists synthesisui ${installed})`)));
+    console.log("");
+    console.log(section("Next"));
+    console.log("");
+    console.log(body("Open your agent here and ask for your first screen:"));
+    console.log("");
+    console.log(snippet(["claude", '"make a landing page for <what you are building>"']));
+    console.log("");
+    console.log(body("When the first screen is done, the agent offers to read it and turn what it decided into your system."));
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import "./copy/connect.pt-BR.js";
 import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
+import { confirm, read } from "./commands/read.js";
 import { advise } from "./commands/advise.js";
 import { align } from "./commands/align.js";
 import { autopilot } from "./commands/autopilot.js";
@@ -49,7 +50,8 @@ const HELP = `synthesisui - bring SynthesisUI design systems into your project
 Usage - deterministic, FREE:
   synthesisui login [options]              connect the CLI to your account (device-flow; --force to switch accounts)
   synthesisui logout                       sign out of this machine (removes the saved token)
-  synthesisui init [options]               write _synthesisui/config.json (target, dirs); --ds to bring one in
+  synthesisui init [options]               start here: the CLI in your devDependencies, your agent wired, no account;
+                                           --ds <slug> brings a published system in instead
   synthesisui list [options]               list the published design systems
   synthesisui list --mine                  your own systems, with their group
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
@@ -70,6 +72,10 @@ Usage - governance (deterministic, FREE):
                                            their variant axes and options, their parts and shape, and
                                            where one is built from another - then the values you repeat,
                                            with file and line. No account, no network, nothing written
+  synthesisui read [--url <dev server>] [--routes /,/x]
+  synthesisui read --confirm [answers.json]  the person's answers become the roles and breaks the check keeps
+                                           read the page you already built and say the system it decided:
+                                           roles, breaks, drift and contrast, with file and line
   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
@@ -120,6 +126,8 @@ Options:
   --dir <path>       consumer project root (default: current directory)
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
+  --package <spec>   init: what to add to devDependencies (default: synthesisui@<this version>)
+  --aesthetic <a>    init: impeccable | none - the layer that creates the first look (default: impeccable, asked in a terminal)
   --name <name>      import: the NAME of the system, which is what its install slug
                      comes from - and the slug never changes. Also the preferred
                      component name for generate.
@@ -160,7 +168,7 @@ Examples:
   synthesisui adopt                        # you already have a system: start here
   synthesisui import --dry                 # see the census before anything is sent
   synthesisui login
-  synthesisui init --target next
+  synthesisui init                         # an empty project: one command, then ask your agent
   synthesisui init --target next --ds halogen   bootstrap + bring a system in
   synthesisui doctor
   synthesisui doctor apps/web packages/ui   # scope the read in a monorepo
@@ -309,6 +317,19 @@ async function main() {
                 registry,
             });
             break;
+        case "read":
+            // What the page already decided - read from the running dev server; writes only _synthesisui/reading.json.
+            // `--confirm [answers.json]` turns the person's answers into rules.json and the contract.
+            if (flags.confirm !== undefined) {
+                await confirm({ dir, answers: typeof flags.confirm === "string" ? flags.confirm : undefined });
+                break;
+            }
+            await read({
+                dir,
+                url: typeof flags.url === "string" ? flags.url : undefined,
+                routes: typeof flags.routes === "string" ? flags.routes.split(",").map((r) => r.trim()).filter(Boolean) : undefined,
+            });
+            break;
         case "adopt":
             // Dry by default: `--write` is the only way anything lands on disk.
             await adopt({
@@ -556,6 +577,8 @@ async function main() {
                 ...(typeof flags["theme-in"] === "string"
                     ? { themeIn: flags["theme-in"] }
                     : {}),
+                ...(typeof flags.package === "string" ? { pkg: flags.package } : {}),
+                ...(typeof flags.aesthetic === "string" ? { aesthetic: flags.aesthetic } : {}),
                 cli: CLI_VERSION,
             });
             break;

package/dist/install-marks.js

@@ -344,7 +344,18 @@
  * `[font-size:var(--text-sm)]` em vez de `[font-size:0.875rem]`. Um componente escrito antes traz os tamanhos à mão. No
  * mesmo PR, o `init` declara a largura da página (`--container-page`) e a seção a escreve pelo nome, não como `1440px`.
  */
-export const MATERIALISER_SINCE = "0.16.499";
+/**
+ * 0.16.499 -> 0.16.500 em 18/10, e o passo 1 dá **SIM** (jornada "a leitura no agente"): o bloco do `CLAUDE.md` de um
+ * sistema adotado ganha os papéis de título e as quebras que a pessoa confirmou (`_synthesisui/ds/<slug>/rules.json`) e,
+ * sem eles, a linha que ensina o agente a oferecer a leitura (`synthesisui read`) e a confirmar (`read --confirm`). Uma
+ * pasta escrita antes não fala de papéis nem da leitura.
+ */
+/**
+ * 0.16.500 -> 0.16.501 em 18/10, e o passo 1 dá **SIM** (jornada "um instalador, uma porta"): num projeto sem sistema, o
+ * bloco do `CLAUDE.md` ensina a leitura da primeira tela em vez do `/sui-import-ds`; com o `rules.json` e o impeccable no
+ * projeto, diz que o revisor dele é só da criação. Uma pasta escrita antes manda o agente importar e não fala do revisor.
+ */
+export const MATERIALISER_SINCE = "0.16.501";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -562,7 +573,19 @@ export const COUNTED_DIFFERENTLY = "this run counts a value as named only when Y
  * de texto escrito à mão (`font-size`, `[font-size:X]`, `text-[X]`), e a família de fonte no colchete do Tailwind deixa de
  * engolir o resto da linha. Um hook anterior diz "limpo" sobre um `[font-size:0.875rem]` com `--text-sm` declarado.
  */
-export const CHECKER_SINCE = "0.16.499";
+/**
+ * 0.16.499 -> 0.16.500 em 18/10, e o passo 1 dá **SIM** (jornada "a leitura no agente"): o hook confere os papéis e as
+ * quebras do `rules.json` (o título fora do papel, a quebra fora do lugar em qualquer elemento, o papel novo dito uma
+ * vez) e acha a raiz pelo projeto - não pela pasta onde o terminal do agente parou, que deixava turnos inteiros sem
+ * conferência. Um hook pinado antes não confere papel nenhum.
+ */
+/**
+ * 0.16.500 -> 0.16.501 em 18/10, e o passo 1 dá **SIM** (jornada "um instalador, uma porta"): o fim do turno pede ao agente,
+ * uma vez, que ofereça a leitura quando a primeira tela aparece num projeto sem sistema nenhum. Um hook pinado antes nunca
+ * oferece. E a checagem por papel lê CSS Modules (`className={styles.h2}`, o tamanho no `.module.css`): um hook anterior
+ * não confere papel nenhum numa página escrita assim.
+ */
+export const CHECKER_SINCE = "0.16.501";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *