synthesisui 0.16.153 → 0.16.154

package/dist/absorb-plan.js

@@ -0,0 +1,154 @@
+import { deltaE, JND } from "./doctor/color-distance.js";
+import { nearestToken } from "./doctor/tokens.js";
+/** Onde cada tipo de valor mora na fundação. `color` é o único com dois segmentos. */
+const HOME = {
+    color: "color",
+    radius: "radius",
+    spacing: "spacing",
+    font: "typography",
+    motion: "motion.durations",
+};
+/** Uma palavra de categoria no começo do nome deles não é família - é a categoria repetida. */
+const CATEGORY = /^(color|colour|radius|rounded|spacing|space|gap|font|type|duration|motion|ease|easing)-/;
+const clean = (name) => name.replace(/^--/, "").toLowerCase();
+/**
+ * O CAMINHO A PARTIR DO NOME DELES, e nada além dele.
+ *
+ * Cor precisa de família E step, e a forma que o mundo real produz é `<família>-<número>` - a mesma que
+ * o censo lê para montar as rampas deles. Sem o número não há step, e inventar um (`.500`) seria
+ * escolher uma posição na escala por eles: aí o valor volta sem caminho e a pessoa decide.
+ *
+ * O namespace é PRESERVADO de propósito: um repo com `--color-lightgray-300` e
+ * `--dashboard-lightgray-300` tem duas famílias, e `dashboard-lightgray` é o nome honesto da segunda.
+ */
+export function pathFor(kind, theirName) {
+    if (!theirName)
+        return "";
+    const bare = clean(theirName).replace(CATEGORY, "");
+    if (!bare)
+        return "";
+    if (kind === "color") {
+        const m = /^(.*[a-z0-9])-(\d{2,4})$/.exec(bare);
+        return m ? `color.${m[1]}.${m[2]}` : "";
+    }
+    return `${HOME[kind]}.${bare}`;
+}
+/**
+ * O TOKEN DELES MAIS PRÓXIMO DESTE VALOR, quando existe um perto o bastante para valer a frase.
+ *
+ * Cor por ΔE76 (2.3 é a diferença que um olho começa a notar; abaixo disso são a mesma cor discutindo).
+ * Comprimento pelo mesmo `nearestToken` que o doctor já usa para dizer "snap to". Motion e tipografia
+ * ficam de fora: 0.2s e 0.25s não são "quase iguais", são durações diferentes de propósito.
+ */
+function nearestOwn(theirs, literal, kind) {
+    if (kind === "color") {
+        let best = null;
+        for (const [name, value] of theirs.byName) {
+            const d = deltaE(literal, value);
+            if (d === null || d === 0)
+                continue;
+            if (best === null || d < best.away)
+                best = { name, value, away: d };
+        }
+        /** Três ΔE: perto o bastante para alguém querer olhar, longe o bastante para não ser óbvio. */
+        if (!best || best.away > JND * 1.3)
+            return undefined;
+        return {
+            name: clean(best.name),
+            value: best.value,
+            away: `${best.away.toFixed(1)} ΔE`,
+        };
+    }
+    if (kind === "radius" || kind === "spacing") {
+        const hit = nearestToken(theirs, literal);
+        return hit
+            ? {
+                name: clean(hit.name),
+                value: hit.value,
+                away: `${hit.delta}${/rem$/.test(literal) ? "rem" : "px"} apart`,
+            }
+            : undefined;
+    }
+    return undefined;
+}
+/**
+ * A PROPOSTA: os valores mais repetidos que o sistema não nomeia, com o caminho quando ele é derivável.
+ *
+ * `theirs` é a tabela do vocabulário DELES (`buildTable({ source: "yours" })`), lida da raiz mesmo
+ * quando a medição é escopada - é o mesmo princípio que já vale no doctor: o vocabulário vem da raiz, só
+ * a leitura é escopada.
+ *
+ * `have` são os caminhos que a fundação já tem, para a proposta nunca sugerir sobrescrever um token
+ * existente com outro valor - isso não é absorver, é repintar.
+ */
+export function absorbPlan(d, theirs, have, cap = 40) {
+    const unnamed = d.repeats.filter((r) => !r.token);
+    const entries = [];
+    for (const r of unnamed) {
+        if (entries.length >= cap)
+            break;
+        const theirNames = theirs.byValue.get(r.literal.toLowerCase()) ?? [];
+        const theirName = theirNames[0];
+        const path = pathFor(r.kind, theirName);
+        const near = nearestOwn(theirs, r.literal, r.kind);
+        /** Já existe na fundação com OUTRO valor: absorver aqui seria repintar o token deles. */
+        if (path && have.has(path))
+            continue;
+        entries.push({
+            value: r.literal,
+            kind: r.kind,
+            files: r.files,
+            count: r.count,
+            path,
+            ...(theirName ? { theirName: clean(theirName) } : {}),
+            ...(near ? { near } : {}),
+        });
+    }
+    return { entries, more: Math.max(0, unnamed.length - entries.length) };
+}
+/** Quantas linhas da proposta ainda precisam de um nome humano. */
+export const needingName = (plan) => plan.entries.filter((e) => !e.path);
+/**
+ * A proposta em texto - e ela lidera pelo que está PRONTO para enviar.
+ *
+ * Uma lista que abre pelas pendências faz parecer que nada pode ser feito hoje; a maioria das linhas de
+ * um repo em migração já tem nome no vocabulário do próprio cliente, e essas viajam sem ninguém digitar
+ * nada.
+ */
+export function describeAbsorb(plan) {
+    const ready = plan.entries.filter((e) => e.path);
+    const pending = needingName(plan);
+    const lines = [];
+    if (plan.entries.length === 0)
+        return [
+            "Nothing to absorb: every repeated value your code writes by hand already has a name in the system.",
+        ];
+    lines.push(`${ready.length} of ${plan.entries.length} values already have a name in YOUR vocabulary - those travel as they are:`);
+    for (const e of ready.slice(0, 8))
+        lines.push(`  ${e.value.padEnd(24)} ${e.path.padEnd(28)} ${e.files} file${e.files === 1 ? "" : "s"}${e.theirName ? ` · your ${e.theirName}` : ""}`);
+    if (ready.length > 8)
+        lines.push(`  (${ready.length - 8} more)`);
+    if (pending.length > 0) {
+        const close = pending.filter((e) => e.near);
+        lines.push("");
+        lines.push(`${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`);
+        for (const e of pending.slice(0, 8))
+            lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
+        if (pending.length > 8)
+            lines.push(`  (${pending.length - 8} more)`);
+        /**
+         * E A LEITURA QUE MUDA O TRABALHO: quando a maioria dos sem-nome está perto de um token que eles já
+         * têm, isto não é uma fila de batismos - é uma fila de NORMALIZAÇÃO, e sai muito mais barato.
+         */
+        if (close.length > 0) {
+            lines.push("");
+            lines.push(`${close.length} of those ${close.length === 1 ? "is" : "are"} within a hair of a token you already have (marked ≈). Those are probably not new names - they are the same decision written twice, and pointing the code at what you have is cheaper than naming them.`);
+        }
+    }
+    /** O teto NUNCA é silencioso: um corte que não se diz lê como "é tudo o que existe". */
+    if (plan.more > 0) {
+        lines.push("");
+        lines.push(`${plan.more} more unnamed values are below the cut - the file holds the ${plan.entries.length} most repeated. Absorb these, re-run, and the next batch appears.`);
+    }
+    return lines;
+}

package/dist/commands/absorb.js

@@ -0,0 +1,211 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { absorbPlan, describeAbsorb, needingName, } from "../absorb-plan.js";
+import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
+import { diagnose, scanSource } from "../doctor/scan.js";
+import { buildTable } from "../doctor/tokens.js";
+import { measuredScope, scopePaths } from "../measured-scope.js";
+import { body, paint, section, snippet } from "../output.js";
+import { loadSystem, walkAll } from "./doctor.js";
+/**
+ * `synthesisui absorb` - O SISTEMA APRENDE O DESIGN QUE O CÓDIGO JÁ TEM.
+ *
+ * O outro sentido da esteira, e o que faltava para o ciclo de migração fechar (dono, 06/08, movendo
+ * design de três apps para `packages/ui`):
+ *
+ *     doctor --migrate   4223 valores que o sistema não nomeia, por frequência
+ *     absorb             ESTE: eles viram tokens do sistema
+ *     upgrade            o repo pega a versão nova
+ *     doctor --fix       agora eles têm nome, e a troca é automática
+ *
+ * DUAS FASES, e a do meio é humana de propósito. A primeira escreve uma PROPOSTA em
+ * `_synthesisui/absorb.json`: cada valor com o caminho derivado do nome que eles já usam, e vazio
+ * quando ninguém nomeia. A pessoa preenche os vazios num arquivo, de uma vez - vinte perguntas no
+ * terminal é como uma migração vira uma tarde perdida. Aí `--send` manda o lote.
+ *
+ * O arquivo é o contrato entre as duas fases, e é revisável por outra pessoa antes de ir: um lote de
+ * tokens novos num sistema compartilhado é exatamente o tipo de mudança que um time quer ver num diff.
+ */
+const FILE = "_synthesisui/absorb.json";
+export async function absorb(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const path = join(root, FILE);
+    if (opts.send)
+        return sendProposal(root, path, opts.registry);
+    const installed = await loadSystem(root);
+    if (!installed.table.slug) {
+        console.log(section("Absorb"));
+        console.log(body("No system installed here, so there is nothing to absorb INTO. `synthesisui list` shows what you can add."));
+        return;
+    }
+    const measured = await measuredScope(root);
+    const rel = scopePaths(measured);
+    const roots = rel.length > 0 ? rel.map((s) => resolve(root, s)) : [root];
+    /**
+     * DUAS TABELAS, e é a diferença entre elas que define o trabalho.
+     *
+     * A nossa diz o que o sistema JÁ nomeia - o que ela nomeia é assunto do `--fix`. A DELES diz como
+     * eles chamam o valor, e é de lá que o nome sai. Lida da RAIZ mesmo quando a medição é escopada: o
+     * vocabulário é do projeto, e um app que pega um token emprestado do `packages/ui` deles não o
+     * redeclara.
+     */
+    let css = "";
+    for await (const file of walkAll([root]))
+        if (/\.(css|scss|sass|less)$/i.test(file))
+            css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+    const theirs = buildTable({ css, source: "yours" });
+    const reports = [];
+    for await (const file of walkAll(roots)) {
+        const source = await readFile(file, "utf8").catch(() => null);
+        if (source === null)
+            continue;
+        reports.push(scanSource(file.slice(root.length + 1), source, installed.table));
+    }
+    const plan = absorbPlan(diagnose(reports), theirs, pathsInSystem(installed.documents), opts.cap ?? 40);
+    console.log(section("What the system could absorb"));
+    console.log(body(paint.dim(`read from ${rel.length > 0 ? rel.join(", ") : "this project"} · your own vocabulary read from the root`)));
+    console.log("");
+    for (const line of describeAbsorb(plan))
+        console.log(body(line));
+    if (plan.entries.length === 0)
+        return;
+    const proposal = {
+        slug: installed.table.slug,
+        at: new Date().toISOString(),
+        scope: rel,
+        entries: plan.entries,
+        more: plan.more,
+    };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(proposal, null, 2)}\n`, "utf8");
+    console.log("");
+    console.log(body(`Written to ${FILE} - nothing was sent.`));
+    const pending = needingName(plan).length;
+    if (pending > 0)
+        console.log(body(`Fill the ${pending} empty \`path\` field${pending === 1 ? "" : "s"} with the name you want (\`color.<family>.<step>\`, \`spacing.<key>\`), delete the lines you do not want, then:`));
+    else
+        console.log(body("Delete the lines you do not want and send the rest with:"));
+    console.log(paint.blue(snippet(["npx synthesisui@latest absorb --send"])));
+}
+/**
+ * OS CAMINHOS QUE A FUNDAÇÃO JÁ TEM, lidos do documento que o `add` deixou ao lado dos tokens.
+ *
+ * Serve para a proposta nunca sugerir escrever num token existente: isso não seria absorver o design
+ * deles, seria repintar uma decisão que eles já tomaram. A plataforma recusa de novo do outro lado - ela
+ * é a autoridade -, e recusar aqui evita a pessoa preencher um nome que vai ser rejeitado.
+ */
+function pathsInSystem(documents) {
+    const out = new Set();
+    const walk = (node, path) => {
+        if (node && typeof node === "object" && !Array.isArray(node))
+            for (const [k, v] of Object.entries(node))
+                walk(v, [...path, k]);
+        else if (typeof node === "string" && path.length > 0)
+            out.add(path.join("."));
+    };
+    for (const doc of documents) {
+        const d = (doc ?? {});
+        const foundations = d.foundations ?? {};
+        const color = (foundations.color ?? {});
+        walk(color.primitives, ["color"]);
+        for (const [key, value] of Object.entries(foundations))
+            if (key !== "color")
+                walk(value, [key]);
+        walk(d.motion?.durations, ["motion", "durations"]);
+        walk(d.motion?.easings, ["motion", "easings"]);
+    }
+    return out;
+}
+/** Manda o lote gravado. Só o que tem caminho viaja - o resto ainda espera um nome. */
+async function sendProposal(root, path, registry) {
+    const raw = await readFile(path, "utf8").catch(() => null);
+    if (!raw) {
+        console.log(section("Absorb"));
+        console.log(body(`No proposal at ${FILE}. Run \`npx synthesisui@latest absorb\` first - it writes one and sends nothing.`));
+        return;
+    }
+    let proposal;
+    try {
+        proposal = JSON.parse(raw);
+    }
+    catch {
+        console.log(section("Absorb"));
+        console.log(body(`${FILE} is not readable JSON anymore. Fix the file, or delete it and run \`absorb\` again.`));
+        return;
+    }
+    const ready = (proposal.entries ?? []).filter((e) => typeof e.path === "string" && e.path.trim().length > 0);
+    const waiting = (proposal.entries ?? []).length - ready.length;
+    if (ready.length === 0) {
+        console.log(section("Absorb"));
+        console.log(body(`Every line in ${FILE} still has an empty \`path\`. A name is the one thing this cannot decide for you.`));
+        return;
+    }
+    /**
+     * O ALVO DECIDE SE ISSO SAI DA MÁQUINA - ver `ProjectConfig.absorb`.
+     *
+     * `code`: o vocabulário canônico é o CSS deles, então a nossa parte é devolver o bloco e a deles é
+     * colar. Nunca escrevemos no arquivo do cliente - e o import seguinte lê os tokens de volta, o que faz
+     * o caminho fechar sem nós tocarmos em nada.
+     */
+    const target = (await readProjectConfig(root)).absorb ?? "system";
+    if (target === "code") {
+        console.log(section("Paste this into your own vocabulary"));
+        console.log(body(paint.dim("Your config says absorbed values belong in your CSS, so nothing was sent.")));
+        console.log("");
+        console.log("  :root {");
+        for (const e of ready)
+            console.log(`    --${e.path.replace(/\./g, "-")}: ${e.value};`);
+        console.log("  }");
+        console.log("");
+        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor cobra them by your own names."));
+        return;
+    }
+    const token = await readToken();
+    if (!token) {
+        console.log(section("Absorb"));
+        console.log(body("Sending needs a login - the tokens land in YOUR system:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest login"])));
+        return;
+    }
+    const base = resolveRegistry(registry);
+    const res = await fetch(`${base}/api/registry/ds/${proposal.slug}/absorb`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+            tokens: ready.map((e) => ({
+                path: e.path.trim(),
+                value: e.value,
+                ...(e.theirName ? { was: e.theirName } : {}),
+            })),
+        }),
+    }).catch(() => null);
+    console.log(section("Absorb"));
+    if (!res?.ok) {
+        console.log(body(res
+            ? `The registry answered ${res.status}. Nothing was absorbed, and ${FILE} is untouched - fix and send again.`
+            : "Could not reach the registry. Nothing was absorbed."));
+        return;
+    }
+    const answer = (await res.json());
+    console.log(body(`${answer.added ?? 0} token${answer.added === 1 ? "" : "s"} are now part of your system${answer.draft ? `, in the v${answer.draft} draft` : ""}.`));
+    for (const s of (answer.skipped ?? []).slice(0, 8))
+        console.log(body(paint.dim(`  skipped ${s.path} - ${s.why}`)));
+    if (waiting > 0)
+        console.log(body(paint.dim(`${waiting} line${waiting === 1 ? "" : "s"} stayed behind with no name. They are still in ${FILE}.`)));
+    /**
+     * E O CICLO SE FECHA AQUI, dito em voz alta.
+     *
+     * Absorver não muda o código: os literais continuam escritos à mão até alguém trocá-los, e agora
+     * existe por quem trocar. Ninguém adivinharia essa ordem - foi ela que faltou na primeira conversa
+     * sobre migração (dono, 06/08).
+     */
+    console.log("");
+    console.log(body("Two commands and the code catches up:"));
+    console.log(paint.blue(snippet([
+        `npx synthesisui@latest upgrade ${proposal.slug}`,
+        "npx synthesisui@latest doctor --fix",
+    ])));
+}

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
+import { describeIntent, intentOf, readProjectConfig } from "../config.js";
 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";
@@ -13,6 +14,7 @@ import { checkableName, readRequests, verifyAndCloseRequests, } from "../doctor/
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
+import { describeScope, measuredScope, scopePaths } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { resolveDeps } from "../stack.js";
 /**
@@ -412,7 +414,32 @@ async function readWiring(root, slug) {
 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));
+    /**
+     * O ESCOPO QUE O IMPORT JÁ GRAVOU - ver `measured-scope.ts`.
+     *
+     * Um caminho passado à mão manda, sempre: quem digitou sabe o que quer. Sem ele, a resposta já está
+     * no disco (`census.json`: `scope` + `usage`), e varrer a raiz ignorando isso foi o que produziu uma
+     * lista de prioridades tirada de um app consumidor num repo de 2787 arquivos (dono, 06/08).
+     */
+    const measured = (opts.scopes ?? []).length > 0
+        ? { system: null, usage: [], from: "none" }
+        : await measuredScope(root);
+    const relScopes = (opts.scopes ?? []).length > 0
+        ? opts.scopes
+        : scopePaths(measured);
+    const scopes = relScopes.map((s) => resolve(root, s));
+    /**
+     * CORRIDA COMPLETA É "NINGUÉM DIGITOU UM CAMINHO", e não "varreu tudo".
+     *
+     * O ledger só guarda retrato de corrida completa, porque a cobertura de um canto na linha do tempo do
+     * projeto lê como o projeto tendo melhorado quando alguém só apontou a ferramenta para outra pasta.
+     * Com o escopo agora vindo do censo, `scopes.length === 0` deixaria de acontecer - e o histórico
+     * pararia de existir em todo repo que tem censo. O que caracteriza a corrida completa é a INTENÇÃO de
+     * medir o projeto, e ela é: nenhum caminho na linha de comando.
+     */
+    const fullRun = (opts.scopes ?? []).length === 0;
+    /** A intenção ordena o relatório, e a precedência é flag > config > default. */
+    const intent = intentOf(await readProjectConfig(root), opts.intent);
     const installed = await loadSystem(root);
     const { recipes, documents } = installed;
     let table = installed.table;
@@ -533,9 +560,24 @@ export async function doctor(opts) {
             : table.source === "yours"
                 ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
                 : `No system installed - ${plural(d.scanned, "file")} read`));
+    /**
+     * ONDE ELE LEU, SEMPRE - e de onde essa decisão veio.
+     *
+     * "2787 files read" sem dizer o universo é um número que a pessoa preenche com o que imagina, e ela
+     * imagina o sistema dela. Quando o escopo veio do censo, a frase nomeia os dois papéis: a pasta que
+     * É o sistema, e os apps que o CONSOMEM.
+     */
     if (scopes.length > 0) {
-        console.log(body(`scope: ${opts.scopes?.join(", ")}`));
+        const said = measured.from === "census" ? describeScope(measured) : null;
+        console.log(body(said ?? `scope: ${relScopes.join(", ")}`));
     }
+    /**
+     * E A INTENÇÃO, em toda rodada, com a data e o jeito de inverter.
+     *
+     * É o que impede uma fase declarada em agosto de ordenar o relatório em dezembro sem ninguém saber
+     * por quê - a mesma regra que fez `not observed since` existir em vez de um `fixed` inferido.
+     */
+    console.log(body(paint.dim(describeIntent(intent))));
     // What a token could never have held, said out loud. A report that quietly
     // drops things is only trustworthy until someone notices, and then it is
     // worth less than one that says too much.
@@ -574,6 +616,15 @@ export async function doctor(opts) {
     // Fonts only count as missing when `init` actually wrote the file - a
     // non-Next project has no fonts.ts and must not be nagged about one.
     const fontsPending = wiring.fontsWritten && !wiring.fontsMapped;
+    /**
+     * A FIAÇÃO É PORTÃO, e não um aviso ao lado de um número.
+     *
+     * Sem o `@import` ou sem o `data-ds`, os tokens não chegam ao navegador. Até 06/08 a tela dizia isso
+     * e, três linhas abaixo, imprimia uma barra de 0% e uma lista de cinco prioridades - se contradizendo
+     * na mesma tela (dono: "fiquei perdido"). Ou o número não significa nada, ou existe uma lista de
+     * prioridades; as duas não cabem juntas.
+     */
+    const blocked = hasSystem && (!wiring.imported || !wiring.scoped);
     const unwired = table.source === "installed" &&
         (!wiring.imported || !wiring.scoped || fontsPending);
     if (unwired) {
@@ -598,10 +649,13 @@ export async function doctor(opts) {
         // working and the faces are not - saying "nothing reaches the browser"
         // there would be false, and a report that overstates is one nobody trusts
         // the next time.
-        const blocked = !wiring.imported || !wiring.scoped;
         if (blocked) {
-            console.log(body(`Until the first two are true, none of the ${table.byName.size} tokens reach the`));
-            console.log(body("browser and the number below cannot mean anything."));
+            /**
+             * A FRASE SEGUE O QUE VEM DEPOIS DELA. Ela dizia "o número abaixo não pode significar nada"
+             * enquanto imprimia o número abaixo; agora não há número abaixo, e prometer um seria a mesma
+             * incoerência ao contrário.
+             */
+            console.log(body(`Until both are true, none of the ${table.byName.size} tokens reach the browser.`));
         }
         else {
             console.log(body("Colour and spacing are working. Type is not: the system's faces"));
@@ -610,6 +664,41 @@ export async function doctor(opts) {
         }
         console.log(body("The exact snippets are in the output of `init`."));
     }
+    /**
+     * E AQUI O RELATÓRIO PARA, quando a fiação está vermelha: uma instrução, e nada mais.
+     *
+     * O que fica de fora é justamente o que não pode ser verdade ainda - a barra de cobertura, a lista de
+     * prioridades e a oferta do `--fix`. O `--fix` é o mais grave: no repo do dono ele teria trocado 217
+     * literais por `var(--ds-…)` que não resolvem em lugar nenhum, e o navegador descarta a declaração -
+     * ou seja, o comando que promete adotar o sistema quebraria a aparência do app.
+     *
+     * O ledger é gravado ANTES de sair: a corrida aconteceu, e o histórico não pode depender de o
+     * projeto estar bem configurado.
+     */
+    if (blocked) {
+        if (fullRun)
+            await appendEvent(root, {
+                kind: "doctor",
+                at: new Date().toISOString(),
+                coverage: d.coverage,
+                named: d.named,
+                ...(d.findings.some((f) => f.crossFamily)
+                    ? { crossFamily: d.findings.filter((f) => f.crossFamily).length }
+                    : {}),
+            }).catch(() => { });
+        console.log("");
+        if (opts.fix) {
+            console.log(body(`--fix is refused while those two are false. ${d.named} of your hand-written values`));
+            console.log(body("do have a name in the system, and swapping them now would point them at"));
+            console.log(body("variables the browser cannot resolve - the declarations would be dropped"));
+            console.log(body("and the page would change. Wire the two lines first."));
+        }
+        else {
+            console.log(body(`${d.named} of the ${d.findings.length} hand-written values found already have a name in`));
+            console.log(body("your system, and that number becomes actionable the moment both are true."));
+        }
+        return;
+    }
     /**
      * SHADCN IS THE MOST LIKELY THING ALREADY IN THE PROJECT, AND THE BRIDGE WAS
      * INVISIBLE.
@@ -671,7 +760,7 @@ export async function doctor(opts) {
      * question a design-system lead asks before paying for anything, and until
      * today the honest answer was that nobody knew.
      */
-    if (hasSystem && measurable && scopes.length === 0) {
+    if (hasSystem && measurable && fullRun) {
         /**
          * E A CONTAGEM DE COINCIDÊNCIAS VAI JUNTO - ver `crossFamily` em `scan.ts`.
          *
@@ -688,7 +777,7 @@ export async function doctor(opts) {
             ...(crossFamily > 0 ? { crossFamily } : {}),
         });
     }
-    if (hasSystem && scopes.length === 0) {
+    if (hasSystem && fullRun) {
         const record = summarize(await readEvents(root));
         if (record.checks >= 2) {
             console.log("");
@@ -716,7 +805,7 @@ export async function doctor(opts) {
      * the considered-and-rejected entries arrive already argued, by the party
      * that actually hit the gap.
      */
-    if (hasSystem && scopes.length === 0) {
+    if (hasSystem && fullRun) {
         // Verification first: whether an ask is still missing is a FACT about
         // the installed css, so the queue re-checks before it reports. A request
         // the build now delivers closes itself and says so - nobody marks done
@@ -1143,18 +1232,31 @@ export async function doctor(opts) {
             cheap: false,
         });
     }
-    for (const r of d.repeats.filter((x) => x.token).slice(0, 3)) {
+    /**
+     * AS DUAS INTENÇÕES ORDENAM ESTA LISTA AO CONTRÁRIO UMA DA OUTRA.
+     *
+     * `adopt`: o que o sistema JÁ nomeia vem primeiro - é troca de uma linha e o `--fix` faz.
+     * `migrate`: o que ele NÃO nomeia vem primeiro - é a decisão de design que a biblioteca tem que
+     * absorver, e é o trabalho de quem está movendo design de um app para um pacote compartilhado.
+     *
+     * As duas listas continuam presentes nos dois modos (dono, 06/08): esconder metade faria a tela
+     * mentir por omissão. Muda a ordem e muda quantos de cada aparecem no teto de cinco.
+     */
+    const migrating = intent.intent === "migrate";
+    const named = d.repeats.filter((x) => x.token);
+    const unnamed = d.repeats.filter((x) => !x.token);
+    for (const r of named.slice(0, migrating ? 2 : 3)) {
         plan.push({
-            rank: 3,
+            rank: migrating ? 4 : 3,
             what: `${r.literal} → ${r.token}`,
             size: `${r.files} file${r.files === 1 ? "" : "s"}`,
             cheap: true,
         });
     }
-    for (const r of d.repeats.filter((x) => !x.token).slice(0, 2)) {
+    for (const r of unnamed.slice(0, migrating ? 3 : 2)) {
         const near = nearestToken(table, r.literal);
         plan.push({
-            rank: 4,
+            rank: migrating ? 3 : 4,
             what: near
                 ? `${r.literal} - name it, or snap to ${near.name}`
                 : `${r.literal} - the system has no name for it`,
@@ -1318,7 +1420,8 @@ export async function doctor(opts) {
         await writeFile(path, `${JSON.stringify(baselineOf(d, {
             at: new Date().toISOString(),
             ...(opts.cli ? { cli: opts.cli } : {}),
-            ...(opts.scopes?.length ? { scope: opts.scopes.join(",") } : {}),
+            /** O escopo EFETIVO, e não a flag: comparar dois universos diferentes inventa regressão. */
+            ...(relScopes.length ? { scope: relScopes.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.`));
@@ -1337,7 +1440,7 @@ export async function doctor(opts) {
             return;
         }
         const verdict = compareToBaseline(d, base, {
-            ...(opts.scopes?.length ? { scope: opts.scopes.join(",") } : {}),
+            ...(relScopes.length ? { scope: relScopes.join(",") } : {}),
         });
         console.log(section(verdict.worse ? "Drift went up" : "Ratchet"));
         for (const line of describeVerdict(verdict))

package/dist/commands/init.js

@@ -15,6 +15,16 @@ export async function init(opts) {
         pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
         componentsDir: opts.componentsDir ?? DEFAULT_CONFIG.componentsDir,
         styles: opts.styles === "tailwind" ? "tailwind" : "css",
+        /**
+         * Gravada COM A DATA, e só quando alguém respondeu. Migração é uma fase que termina, e uma fase sem
+         * data é a etiqueta que envelhece em silêncio - o doctor imprime as duas em toda rodada.
+         */
+        ...(opts.intent === "migrate" || opts.intent === "adopt"
+            ? { intent: opts.intent, intentAt: new Date().toISOString() }
+            : {}),
+        ...(opts.absorb === "code" || opts.absorb === "system"
+            ? { absorb: opts.absorb }
+            : {}),
     };
     await writeProjectConfig(root, config);
     console.log("✓ wrote _synthesisui/config.json");
@@ -22,6 +32,10 @@ export async function init(opts) {
     console.log(`  pagesDir:      ${config.pagesDir}`);
     console.log(`  componentsDir: ${config.componentsDir}`);
     console.log(`  styles:        ${config.styles}`);
+    if (config.absorb)
+        console.log(`  absorb:        ${config.absorb}${config.absorb === "code" ? "  (we hand you the CSS block; your file stays yours)" : "  (absorbed values become tokens of the system)"}`);
+    if (config.intent)
+        console.log(`  intent:        ${config.intent}${config.intent === "migrate" ? "  (the doctor leads with what your system does not name yet)" : "  (the doctor leads with what your system already names)"}`);
     // --ds bootstraps the project with a system in one step (tokens + philosophy
     // + rules + CLAUDE.md all arrive via `add`).
     if (opts.ds) {

package/dist/commands/summary.js

@@ -0,0 +1,79 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { measuredScope } from "../measured-scope.js";
+import { body, paint, section, snippet } from "../output.js";
+/**
+ * `synthesisui summary <slug>` - AS QUATRO LINHAS DO PRIMEIRO MINUTO, impressas por um programa.
+ *
+ * A skill `sui-init` já mandava terminar em quatro linhas, e listava o que nunca deveria aparecer
+ * nelas: quantos arquivos foram varridos, quanto tempo levou, quais leitores rodaram, o que o ledger
+ * diz. O fechamento que o dono recebeu em 06/08 tinha ~400 palavras e violava as duas regras - com
+ * três dos quatro parágrafos falando do AGENTE e não do sistema dele:
+ *
+ *     "my notes from 2026-08-05 carry two confirmed defects"          a memoria do agente
+ *     "the generator had been deleted, so I rebuilt it"               o retrabalho do agente
+ *     "a census regression I stripped by hand"                        o conserto do agente
+ *
+ * E duas daquelas advertências estavam DESATUALIZADAS: os dois defeitos do `--fix` foram consertados
+ * na 0.16.153, então a skill assustou o usuário com um bug que não existe mais.
+ *
+ * Mais prosa proibindo não conserta isso. O que o agente tem em mãos no fim é justamente o próprio
+ * trabalho dele, e a atração de reportá-lo vence uma linha de proibição a sessenta linhas de distância.
+ * Então o fechamento sai das mãos dele: este comando sabe as contagens (o censo está no disco), sabe a
+ * versão instalada (o `.lock`), e recebe o resto por flag. Um agente que executa isto não tem o que
+ * compor - e uma anotação velha dele não tem por onde entrar.
+ *
+ * LOCAL, E NUNCA FALHA. Sem censo ele ainda diz o essencial; sem rede ele não perde nada, porque nada
+ * aqui é remoto.
+ */
+export async function summary(slug, opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const census = await readFile(join(root, "_synthesisui", "census.json"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    const lock = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    const measured = await measuredScope(root);
+    const name = lock?.name ?? slug;
+    /**
+     * `looks`, NUNCA `components`.
+     *
+     * `components` é a lista de candidatos que o portão avaliou - 128 no repo do dono, contra os 36 que
+     * o sistema realmente tem. Dizer 128 no primeiro minuto é prometer quatro vezes o que foi entregue,
+     * e o número certo já estava no mesmo arquivo.
+     */
+    const components = census?.looks ? Object.keys(census.looks).length : null;
+    const tokens = census?.declared ? Object.keys(census.declared).length : null;
+    console.log(section(`${name} is yours`));
+    /**
+     * LINHA 1 - O QUE ELE TEM, nas contagens dele. Nunca "36 de 128 candidatos", nunca "2787 arquivos":
+     * o que importa no primeiro minuto é o tamanho do que ele ganhou e de onde saiu.
+     */
+    const from = measured.system ? `, read out of ${measured.system}` : "";
+    console.log(body(components != null && tokens != null
+        ? `${components} components and ${tokens} of your own tokens${from}.`
+        : `Installed${lock?.version ? ` at v${lock.version}` : ""}${from}.`));
+    /**
+     * LINHA 2 - AS DUAS VERSÕES E O CAMINHO DE VOLTA, com os números que a PLATAFORMA deu.
+     *
+     * Escrever "v1" e "v2" aqui por conta própria já esteve errado uma vez: enquanto o nascimento
+     * publicava uma baseline, o import caía na v2 e o congelamento produzia a v3. Então os números
+     * chegam por flag, e sem eles esta linha simplesmente não é dita.
+     */
+    if (opts.base != null && opts.draft != null) {
+        console.log(body(`v${opts.base} is your code as it is today${opts.fixes ? ` · v${opts.draft} adds ${opts.fixes} deterministic ${opts.fixes === 1 ? "fix" : "fixes"}` : ` · v${opts.draft} is the draft`}.`));
+        console.log(body(paint.dim(`Back to v${opts.base} is one click: /dashboard/mine/${slug}/publish`)));
+    }
+    /**
+     * LINHA 3 - O QUE FAZER AGORA, e é uma coisa só.
+     *
+     * As duas linhas de fiação são o portão de tudo o mais: sem elas nenhum token chega ao navegador e
+     * todo número seguinte é vazio. O `doctor` diz isso melhor e com o estado real, então o próximo passo
+     * é ele - não uma explicação nossa aqui.
+     */
+    console.log("");
+    console.log(body("Two lines wire it up, and `init` printed both:"));
+    console.log(body(paint.dim(`  @import "./_synthesisui/ds/${slug}/tokens.css";   and   data-ds="${slug}" on <html>`)));
+    console.log(paint.blue(snippet(["npx synthesisui@latest doctor"])));
+}

package/dist/config.js

@@ -98,12 +98,66 @@ export async function readProjectConfig(root) {
                 ? parsed.componentsDir
                 : DEFAULT_CONFIG.componentsDir,
             styles: parsed.styles === "tailwind" ? "tailwind" : "css",
+            /**
+             * A INTENÇÃO NÃO TEM DEFAULT AQUI, de propósito.
+             *
+             * Um default silencioso é uma decisão nossa vestida de decisão deles: quem não respondeu não
+             * escolheu, e o doctor tem que poder dizer "ninguém declarou" em vez de ordenar por um palpite.
+             * Quem consome isto é `intentOf`, que separa os três casos.
+             */
+            ...(parsed.intent === "migrate" || parsed.intent === "adopt"
+                ? { intent: parsed.intent }
+                : {}),
+            ...(typeof parsed.intentAt === "string" && parsed.intentAt
+                ? { intentAt: parsed.intentAt }
+                : {}),
+            /** Sem valor gravado o comando usa `system`, que é o default do produto e não uma suposição. */
+            ...(parsed.absorb === "code" || parsed.absorb === "system"
+                ? { absorb: parsed.absorb }
+                : {}),
         };
     }
     catch {
         return DEFAULT_CONFIG;
     }
 }
+/**
+ * A PRECEDÊNCIA, num lugar só: flag > config > default.
+ *
+ * E ela é IMPRESSA por quem chama, sempre. Estado persistido que não se anuncia é a etiqueta que
+ * envelhece em silêncio - o mesmo defeito que a tela de causas acabou de perder (dono, 06/08). Uma
+ * linha dizendo "migrate, definido em 06/08, --adopt inverte" transforma estado velho em fato.
+ *
+ * O default é `adopt` porque é o que uma pessoa com um sistema instalado quer na maioria dos dias, e
+ * porque é o único dos dois cuja lista tem conserto automático (`--fix`). Migrar é uma fase, e uma
+ * fase se declara.
+ */
+export function intentOf(config, flag) {
+    if (flag === "migrate" || flag === "adopt")
+        return { intent: flag, from: "flag" };
+    if (config.intent)
+        return {
+            intent: config.intent,
+            from: "config",
+            ...(config.intentAt ? { at: config.intentAt } : {}),
+        };
+    return { intent: "adopt", from: "default" };
+}
+/** A frase que acompanha o relatório - ver `intentOf` para por que ela é obrigatória. */
+export function describeIntent(source) {
+    const what = source.intent === "migrate"
+        ? "reading as a MIGRATION - values your system does not name yet come first"
+        : "reading as ADOPTION - values your system already names come first";
+    const where = source.from === "flag"
+        ? "this run only"
+        : source.from === "config"
+            ? `set in _synthesisui/config.json${source.at ? ` on ${source.at.slice(0, 10)}` : ""}`
+            : "nobody declared one, so this is the default";
+    const flip = source.intent === "migrate"
+        ? "`doctor --adopt` flips it"
+        : "`doctor --migrate` flips it";
+    return `${what} · ${where} · ${flip}`;
+}
 /** Writes the project config (committable, plain JSON). */
 export async function writeProjectConfig(root, config) {
     const path = projectConfigPath(root);

package/dist/doctor/frozen.js

@@ -19,7 +19,19 @@
  * actually differs between the two schemes; a role that is the same in both
  * costs nothing to spell either way, and this stays quiet about it.
  */
-const PRIMITIVE = /^\{color\.([a-z0-9]+)\.([a-z0-9]+)\}$/i;
+/**
+ * A GRAMÁTICA DE UMA REF DE PRIMITIVA, e ela recusava hífen nos DOIS segmentos.
+ *
+ * Contada em 06/08: a mesma pergunta era feita por quatro regexes e as quatro discordavam - duas
+ * aceitavam hífen só na família, uma aceitava nos dois, e esta em nenhum. Consequência medida no repo do
+ * dono, que tem as famílias `royal-blue`, `vivid-pink` e `electric-indigo`: toda ref para elas parseava
+ * como nada aqui, e esta checagem passava calada por cima delas - um achado que não existe é
+ * indistinguível de um achado que não há.
+ *
+ * Gêmea de `PRIMITIVE_REF_PATTERN` em `libs/ds-contracts/src/token-ref.ts`, copiada e não importada
+ * porque o CLI é publicado standalone. O spec ao lado assere a fonte da regex nos dois lados.
+ */
+const PRIMITIVE = /^\{color\.([a-z0-9-]+)\.([a-z0-9-]+)\}$/i;
 const BACKGROUND = /^background(-color)?$/;
 const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 function* colorBindings(node, where) {

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
 import { advise } from "./commands/advise.js";
@@ -19,6 +20,7 @@ import { mcp } from "./commands/mcp.js";
 import { refit } from "./commands/refit.js";
 import { request } from "./commands/request.js";
 import { status } from "./commands/status.js";
+import { summary } from "./commands/summary.js";
 import { sync } from "./commands/sync.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
@@ -99,6 +101,10 @@ Options:
   --strict           doctor: exit 1 when drift is found in THIS repo (for CI)
   --strict-system    doctor: also exit 1 when the system itself is inconsistent
   --verbose          doctor: every finding, file by file (default is a summary)
+  --send             absorb: send the batch you reviewed (default writes the file)
+  --migrate          doctor: lead with what your system does NOT name yet - the
+                     order for moving design INTO a shared package
+  --adopt            doctor: lead with what your system already names (default)
   --laws             doctor: show every usage law, not just the busiest components
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
@@ -279,9 +285,57 @@ async function main() {
                  */
                 ...(flags.write === true ? { write: true } : {}),
                 ...(flags["write-baseline"] === true ? { writeBaseline: true } : {}),
+                /**
+                 * A INTENÇÃO DESTA RODADA - atalho para `config.json`, ver `intentOf`.
+                 *
+                 * Duas flags e não um valor (`--intent=migrate`), porque o que se digita no meio de uma tarefa
+                 * é uma palavra: `--migrate` ou `--adopt`.
+                 */
+                ...(flags.migrate === true
+                    ? { intent: "migrate" }
+                    : flags.adopt === true
+                        ? { intent: "adopt" }
+                        : {}),
                 cli: CLI_VERSION,
             });
             break;
+        case "absorb":
+            /**
+             * O OUTRO SENTIDO: o sistema aprende o design que o código já tem - ver `commands/absorb.ts`.
+             *
+             * Sem flag ESCREVE uma proposta e não fala com a rede; `--send` manda o lote. A fase do meio é
+             * humana de propósito: nomear uma cor é decisão de design.
+             */
+            await absorb({
+                dir,
+                registry,
+                ...(flags.send === true ? { send: true } : {}),
+            });
+            break;
+        case "summary": {
+            /**
+             * AS QUATRO LINHAS DO PRIMEIRO MINUTO - ver `commands/summary.ts`.
+             *
+             * Existe para tirar o fechamento do `sui-init` das mãos do agente: ele terminou com ~400 palavras
+             * sobre o próprio trabalho, incluindo duas advertências já desatualizadas (dono, 06/08).
+             */
+            /** `args` já exclui o comando - o slug é o primeiro posicional, como em `template <slug>`. */
+            const target = args[0];
+            if (!target) {
+                console.log("usage: synthesisui summary <slug> [--base N --draft N --fixes N]");
+                break;
+            }
+            const num = (v) => typeof v === "string" && /^\d+$/.test(v)
+                ? Number.parseInt(v, 10)
+                : undefined;
+            await summary(target, {
+                dir,
+                ...(num(flags.base) != null ? { base: num(flags.base) } : {}),
+                ...(num(flags.draft) != null ? { draft: num(flags.draft) } : {}),
+                ...(num(flags.fixes) != null ? { fixes: num(flags.fixes) } : {}),
+            });
+            break;
+        }
         case "status":
             /** A resposta do dia a dia no terminal - ver `commands/status.ts`. Local primeiro. */
             await status({ dir, registry, cli: CLI_VERSION });
@@ -338,11 +392,28 @@ async function main() {
                 : undefined;
             const ds = typeof flags.ds === "string" ? flags.ds : undefined;
             const styles = typeof flags.styles === "string" ? flags.styles : undefined;
+            /**
+             * A INTENÇÃO, gravada com a data - ver `ProjectConfig.intent`.
+             *
+             * Aceita as duas formas porque as duas são naturais: `--intent migrate` quando um agente monta o
+             * comando, `--migrate` quando uma pessoa digita.
+             */
+            const intent = typeof flags.intent === "string"
+                ? flags.intent
+                : flags.migrate === true
+                    ? "migrate"
+                    : flags.adopt === true
+                        ? "adopt"
+                        : undefined;
             await init({
                 dir,
                 registry,
                 target,
                 pagesDir,
+                ...(flags.absorb === "code" || flags.absorb === "system"
+                    ? { absorb: flags.absorb }
+                    : {}),
+                ...(intent ? { intent } : {}),
                 componentsDir,
                 styles,
                 ds,

package/dist/measured-scope.js

@@ -0,0 +1,63 @@
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const EMPTY = { system: null, usage: [], from: "none" };
+/** Existe como diretório? Um escopo gravado e depois renomeado não pode derrubar o comando. */
+async function present(root, rel) {
+    return stat(resolve(root, rel)).then((s) => s.isDirectory(), () => false);
+}
+/**
+ * Lê `_synthesisui/census.json` e devolve o que ele diz sobre ONDE.
+ *
+ * Só caminhos que ainda existem: o censo é uma foto de quando o import rodou, e uma pasta renomeada
+ * desde então não pode fazer o doctor estourar - ela simplesmente sai da lista, e a lista vazia cai no
+ * comportamento antigo (a raiz).
+ */
+export async function measuredScope(root) {
+    const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
+    if (!raw)
+        return EMPTY;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return EMPTY;
+    }
+    const scope = typeof parsed.scope === "string" && parsed.scope.trim()
+        ? parsed.scope.trim()
+        : null;
+    const usage = Array.isArray(parsed.usage)
+        ? parsed.usage.filter((u) => typeof u === "string" && !!u.trim())
+        : [];
+    const system = scope && (await present(root, scope)) ? scope : null;
+    const kept = [];
+    for (const u of usage)
+        if (await present(root, u))
+            kept.push(u);
+    if (!system && kept.length === 0)
+        return EMPTY;
+    return { system, usage: kept, from: "census" };
+}
+/**
+ * As pastas a LER, na ordem em que importam - o sistema primeiro.
+ *
+ * A ordem não é cosmética: ela decide qual arquivo entra primeiro no relatório e, com teto de
+ * anotações no CI, decide o que chega ao PR.
+ */
+export function scopePaths(m) {
+    return [...(m.system ? [m.system] : []), ...m.usage];
+}
+/** Como dizer o que foi lido. Uma leitura que não declara o universo é um número sem denominador. */
+export function describeScope(m) {
+    if (m.from === "none")
+        return null;
+    const parts = [
+        ...(m.system ? [`${m.system} (the system)`] : []),
+        ...(m.usage.length > 0
+            ? [
+                `${m.usage.join(", ")} (${m.usage.length === 1 ? "consumer" : "consumers"})`,
+            ]
+            : []),
+    ];
+    return `read from your census: ${parts.join(" · ")}`;
+}

package/dist/skill-init.js

@@ -32,20 +32,22 @@ visual, semantic and functional parity, without supposing and without inventing
 
 ## THE SHAPE OF THIS RUN, AND WHY IT IS THIS SHAPE
 
-Four questions, asked before anything that needs an answer. Then silence, then four lines.
+Five questions, asked before anything that needs an answer. Then silence, then four lines.
 
 \`\`\`
 1  environment      which agent they work in - and what that agent can actually get
 2  authorisation    may we optimise after importing, and which parts
 3  project          WHICH folder becomes the system (the only unavoidable choice)
 4  identity         name, primary, theme - each already answered by the census
+5  intent           adopting the system, or migrating design INTO it
+                    (+ where absorbed values live, only if they are migrating)
 ---- nobody waits from here on ----
-   import v1  ->  freeze v1  ->  apply what they authorised  ->  four lines
-5  offer            put the tokens back into their code
+   init  ->  import  ->  freeze  ->  apply what they authorised  ->  four lines
+6  offer            the two lines that wire it up
 \`\`\`
 
 **Every question is asked before the work, and the work starts during the questions.** A person who
-answers four things in ninety seconds and then watches one bar has had a good four minutes; the same
+answers five things in ninety seconds and then watches one bar has had a good four minutes; the same
 person interrupted twice mid-silence has had a bad twenty (dono, 01/08).
 
 **What runs in parallel, precisely.** The UNSCOPED census - \`npx synthesisui import --dry\` - needs no
@@ -161,6 +163,59 @@ in the \`sui-import-ds\` skill; do not reinvent it here, and do not ask anything
 
 ---
 
+## 5. INTENT
+
+The one question the census cannot answer, and the only one whose answer changes what a later command
+puts first.
+
+\`\`\`
+What are you doing with this system?
+
+  Adopting it (recommended)   make the code use the system. The doctor leads with the
+                              values your system already names - those have a one-line
+                              fix, and \`doctor --fix\` does them.
+  Migrating into it           you are moving design out of your apps and into the shared
+                              package. The doctor leads with the values your system does
+                              NOT name yet, by frequency - those are the tokens the
+                              library still has to absorb.
+\`\`\`
+
+Both lists exist in both modes. The answer decides the ORDER, and the order decides what somebody
+does first - measured on a real monorepo (dono, 06/08): with no intent declared, four of the five
+suggestions came out of a consumer app, led by a colour that does not belong to the system's palette
+at all. The same number is noise under one intent and the strongest candidate in the repo under the
+other.
+
+Pass the answer straight through:
+
+\`\`\`
+npx synthesisui@latest init --intent adopt      (or --intent migrate)
+\`\`\`
+
+**One follow-up, and ONLY when they chose migrating.** Absorbing is what a migration does; asking an
+adopter where absorbed values would go is asking about a command they will not run this month.
+
+\`\`\`
+When your system absorbs a value, where should it live?
+
+  In the system (recommended)   it becomes a token of the design system, and the
+                                tokens.css it generates starts emitting it
+  In your own CSS               we hand you the block and you paste it into your
+                                vocabulary; the next import reads it back as a
+                                token you declared
+\`\`\`
+
+Then \`--absorb system\` or \`--absorb code\` on the same \`init\`. Both answers are real: the second exists
+because in some teams the canonical vocabulary IS their stylesheet, and in that case our part is to hand
+over the snippet - never to write in their file.
+
+**Run \`init\` even when nothing else needs it.** It writes \`_synthesisui/config.json\` - the committed
+file that holds \`target\`, \`pagesDir\`, \`componentsDir\`, \`styles\` and this intent - and until 06/08 this
+run never called it: a full first run left no config at all, so \`template\` and \`component\` fell back to
+defaults and the intent had nowhere to live (dono, 06/08).
+
+---
+
 ## THE SILENT PART
 
 Now nobody is asked anything.
@@ -209,46 +264,46 @@ answers 400, and a 400 in a first run reads as a broken product.
 
 ---
 
-## 5. THE FOUR LINES
+## 6. THE FOUR LINES
 
-This is the whole point of the run. Four lines, their numbers, no adjectives.
+This is the whole point of the run, and **it is not yours to compose.** Run this and print nothing
+else:
 
 \`\`\`
-SignalUI is yours - 275 components and 92 of your own tokens, read out of packages/ui.
-
-v2 is frozen: your system exactly as your code has it today. It never moves.
-v3 is what you are looking at - the same system with 118 deterministic fixes: contrast on
-text only, lengths onto your own scale, near-identical colours unified.
-
-Back to v2 is one click: /dashboard/mine/signalui/publish
+npx synthesisui@latest summary <slug> --base <base> --draft <draft> --fixes <how many>
 \`\`\`
 
-**THE VERSION NUMBERS COME FROM THE RESPONSE, NEVER FROM THIS EXAMPLE.** \`optimize\` answers with
-\`base\` and \`draft\`, and those are the two numbers to print. Writing "v1" here would have been wrong:
-a system already publishes its baseline at birth, so an import writes into v2 and the freeze produces
-v3. Proved against production before this skill ever ran (05/08) - and a first screen that points at
-the wrong version to restore is worse than no version at all.
+It prints their component count, their own token count, where the system was read from, the two
+versions with the way back, and the one thing to do next. The numbers for \`--base\` and \`--draft\` come
+from the \`optimize\` RESPONSE - never invented here, because the platform is what numbers a version.
 
-**What must never be in those lines:** how many files we scanned, how long it took, which readers
-ran, what the ledger says. All of that is in the report and none of it is what somebody wants in the
-first minute of owning a system.
+**Why a command instead of four lines you write.** The last screen of this run has ended long, more
+than once - up to four hundred words, with three of its four paragraphs about the AGENT rather than
+about their system: notes from a previous session, a generator that had been deleted and rebuilt, a
+regression stripped by hand. Two of those notes were also out of date, which is worse than verbose: it
+warned somebody about defects that no longer existed (dono, 06/08).
 
-**What must always be there:** the count of their components, the count of their own tokens, and the
-way back.
+The pull to report your own work at the end of a long job beats a rule written sixty lines earlier. So
+the rule became a program. What you have in hand when the run ends - your notes, your retries, your
+repairs - has no way into a block that a command prints.
 
-## 6. THE OFFER
+**Anything you think belongs on that screen and is not in the command's output does not belong on that
+screen.** If it is a real finding, it is already in the report or in the causes screen; if it is about
+what you did, it is not theirs.
 
-One question, and only if there is something to offer - the doctor already knows the number.
+## 7. THE OFFER
 
-\`\`\`
-340 hand-written values in your code have a token in your system now.
-Want me to replace them? It only touches values your system names, and you read the diff.
+There is exactly one thing to offer, and it is not the fix: it is the two lines that wire the system
+up. Until a stylesheet imports the tokens and an element carries \`data-ds\`, none of the tokens reach
+the browser.
 
-    npx synthesisui@latest doctor --fix
-\`\`\`
+\`summary\` already prints both. Say nothing more about them.
 
-If the number is zero, say nothing. An offer with no subject is noise, and this run ends better
-short.
+**Never offer \`doctor --fix\` here.** It was offered for a while, with the number of values that have a
+token - and on an unwired project that swap points hundreds of literals at variables the browser
+cannot resolve, so the declarations are dropped and the page changes (dono, 06/08: 210 values, in a
+project where neither line was in place). The doctor itself now refuses in that state, and it is the
+right place for the offer: it can see the wiring, and this run cannot see what they do after it ends.
 
 ---
 
@@ -261,6 +316,10 @@ short.
 - **Never applies an optimisation without a frozen v1**, and never reports one without the way back.
 - **Never claims parity between agents.** The post-write check exists in one of them. Saying
   otherwise is the kind of sentence that ends a trial.
-- **Never ends long.** If the last screen needs scrolling, the run failed at the last step.
+- **Never ends long.** If the last screen needs scrolling, the run failed at the last step. The last
+  screen is \`summary\`'s output and nothing else - see section 6 for why that stopped being a rule and
+  became a command.
+- **Never offers a fix that the wiring blocks.** A swap to tokens that do not reach the browser
+  changes the page, and it would be our command that changed it.
 `;
 export const INIT_SKILL_PATH = ".claude/skills/sui-init/SKILL.md";

package/package.json

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