synthesisui 0.16.83 → 0.16.86

package/dist/commands/import.js

@@ -5,17 +5,19 @@ import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../c
 import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, } from "../doctor/call-sites.js";
+import { asCatalogueTable, describeFallback, fetchCatalogue, } from "../doctor/catalogue-fetch.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
-import { describeGate, gateComponent, groupSkips, } from "../doctor/component-gate.js";
+import { describeGate, gateComponent, groupSkips, SCREENS_FOR_SYSTEM, } from "../doctor/component-gate.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { countShape, describeCoverage, summarizeCoverage, } from "../doctor/coverage.js";
-import { crosswalk, isLibrary, observedRules } from "../doctor/crosswalk.js";
+import { crosswalk, floorSize, isLibrary, observedRules, useLiveCatalogue, } from "../doctor/crosswalk.js";
 import { moduleImports, readModuleCss, readModuleUsage, transcribeModule, } from "../doctor/css-modules.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
+import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
 import { buildTable } from "../doctor/tokens.js";
 import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
@@ -214,8 +216,36 @@ function distinctValues(d) {
     }
     return kept.sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
 }
+/**
+ * WHICH SCREEN A FILE BELONGS TO.
+ *
+ * The route segment, because that is what a framework already decided: everything under
+ * `app/dashboard/audience` is one screen however deep the folder goes. Route GROUPS are
+ * skipped - `(dashboard)` is an organisational parenthesis, not a place a person visits.
+ *
+ * For a project with no `app/` or `pages/`, the first two folders are the closest honest
+ * answer, and a library never reaches this because the test is skipped there.
+ */
+function screenOf(rel) {
+    const parts = rel.split("/");
+    const i = parts.findIndex((p) => p === "app" || p === "pages");
+    if (i === -1)
+        return parts.slice(0, 2).join("/");
+    const after = parts.slice(i + 1).filter((p) => !p.startsWith("("));
+    return `${parts[i]}/${after.slice(0, 2).join("/")}`;
+}
 export async function takeCensus(root, opts) {
     const scopeLabel = opts?.scopeLabel;
+    /**
+     * THE LIVE CATALOGUE, once, before anything is matched.
+     *
+     * The written table had 26 names against a catalogue of 41, so twenty of our own
+     * components were invisible to matching and their `Textarea` did not meet our
+     * `textarea` (dono, 01/08). Fetched rather than shipped, and the fallback is announced
+     * with what it costs - a smaller answer is fine, a silently smaller one is not.
+     */
+    const fetched = await fetchCatalogue(opts?.registry);
+    useLiveCatalogue(fetched.ok ? asCatalogueTable(fetched.index) : null);
     const css = await harvestOwnCss(root);
     const table = buildTable({ css, source: "yours" });
     const schemes = parseSchemeBlocks(css);
@@ -243,8 +273,25 @@ export async function takeCensus(root, opts) {
     const dirs = new Map();
     /** Parent → child → the files that put one inside the other. */
     const nesting = new Map();
+    /**
+     * WHAT IS COUNTABLE, COUNTED - so the reader decides instead of searching.
+     *
+     * The skill's theme section said "go and look" and listed five places to grep; a real run
+     * swept for motion and icon libraries too, which it never asked for (dono, 01/08).
+     * Searching is a tool call, its whole output lands in the context, and two readers
+     * sweeping the same repo bring back different slices. All of this is one more pass over
+     * files already open. See `signals.ts`.
+     */
+    const signals = emptySignals();
+    const importTally = new Map();
     /** Component → what its own definition names and whether it forwards the rest. */
     const propsOf = new Map();
+    /**
+     * Component → the distinct SCREENS that compose it, which is what separates a design
+     * system from a folder: 242 of 271 in a real app live on one screen or none, and
+     * filtering them takes the vitrine from 271 to 29 (dono, 01/08).
+     */
+    const screensOf = new Map();
     /** Component → the axes its own `cva` declares. See `variant-read.ts`. */
     const variantAxes = new Map();
     /** How much came out of CSS Modules, for the coverage report. */
@@ -282,6 +329,7 @@ export async function takeCensus(root, opts) {
             }
         }
         sources.push({ file: rel, source: src });
+        readSignalsInto(signals, importTally, rel, src);
         reports.push(scanSource(rel, src, table));
         // Stories and tests compose components to SHOW them; counting those as the
         // product's own composition is the same lie the colour census told before
@@ -299,6 +347,14 @@ export async function takeCensus(root, opts) {
             // HOW IT IS USED, not only what it is: which props people pass, what it passes
             // on, and what shows up inside it. See `call-sites.ts`.
             readNesting(rel, src, nesting);
+            // Which screen this file belongs to, and what it composes. One pass, and the
+            // answer is a count of PLACES rather than of occurrences - a loop is one place.
+            const screen = screenOf(rel);
+            for (const m of src.matchAll(/<([A-Z][A-Za-z0-9_]*)/g)) {
+                const at = screensOf.get(m[1]) ?? new Set();
+                at.add(screen);
+                screensOf.set(m[1], at);
+            }
             const found = [];
             for (const d of scanDefinitions(rel, src)) {
                 const verdict = gateComponent({
@@ -346,6 +402,15 @@ export async function takeCensus(root, opts) {
                  * paid for twice already.
                  */
                 const v = transcribeVariants(src, declaredValues);
+                /**
+                 * THE RESTING OPTION, from the definition itself. `cva` says it in
+                 * `defaultVariants`; a lookup-record component says it in the destructuring -
+                 * `{ variant = "body-md" }` - and reading past that left every style behind a
+                 * `[data-variant]` selector nothing sets, so a real Text previewed as bare
+                 * unstyled words (dono, 01/08).
+                 */
+                const destructured = readDefinitionProps(found[0].name, src).defaults;
+                const defaults = { ...destructured, ...v.defaults };
                 /**
                  * THE CSS MODULE, if this component styles that way.
                  *
@@ -418,9 +483,7 @@ export async function takeCensus(root, opts) {
                         ...(tag ? { rootTag: tag } : {}),
                         ...(layers.length > 0 ? { layers } : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
-                        ...(Object.keys(v.defaults).length > 0
-                            ? { defaults: v.defaults }
-                            : {}),
+                        ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
                     };
                 }
                 // Their variant DEFINITION beats what usage happened to pick, and it is the
@@ -440,6 +503,51 @@ export async function takeCensus(root, opts) {
     })));
     const d = diagnose(reports);
     const allComposed = tallyToInventory(tally, 400);
+    /**
+     * THE FEATURE FILTER, after the walk - because the count needs every file.
+     *
+     * A component composed on one screen is that screen's own markup; two screens is a
+     * decision the product shares. Measured on a real app: 242 of 271 live on one screen or
+     * none, and filtering them takes the vitrine from 271 to 29 - `Table`, `Tag`, `Tooltip`,
+     * `Button`, `Loader`, `Header` (dono, 01/08).
+     *
+     * SKIPPED FOR A LIBRARY, and this is the whole reason the test is here rather than in
+     * the walk: a library composes nothing inside itself, so every export would read as
+     * used on no screen. Measured the same way `isLibrary` measures it, from the tally
+     * rather than from a second opinion.
+     */
+    /**
+     * NO SCREENS MEANS NO TEST, and this is the guard rather than a component count.
+     *
+     * A first version required four components before calling something a library, and a
+     * scope with three had every export filtered as a feature - which is the failure this
+     * test was built to prevent, arriving from the other side (spec, 01/08).
+     *
+     * The honest question is simpler: does this scope HAVE screens? A `packages/ui` has no
+     * `app/` and no `pages/`, so there is nothing to count and the count would be zero for
+     * everything. An app has them, and then the number means something.
+     */
+    const hasScreens = [...screensOf.values()].some((at) => [...at].some((s) => s.startsWith("app/") || s.startsWith("pages/")));
+    if (hasScreens) {
+        const keep = [];
+        for (const d of defined) {
+            const screens = screensOf.get(d.name)?.size ?? 0;
+            if (screens >= SCREENS_FOR_SYSTEM) {
+                keep.push(d);
+                continue;
+            }
+            skips.push({
+                name: d.name,
+                file: d.file,
+                why: "feature",
+                because: screens === 0
+                    ? `\`${d.name}\` is composed on no screen at all - it is markup nothing reaches yet`
+                    : `\`${d.name}\` is composed on one screen only, so it is that screen's own markup rather than a decision the product shares. Two screens is the line, and the count is from your files`,
+            });
+        }
+        defined.length = 0;
+        defined.push(...keep);
+    }
     /**
      * THE EVIDENCE PASS - a second walk that touches ONE reading.
      *
@@ -670,6 +778,27 @@ export async function takeCensus(root, opts) {
             Object.keys(part.base).length +
             Object.keys(part.dark).length +
             Object.values(part.states).reduce((k, block) => k + Object.keys(block).length, 0), 0), 0));
+    if (fetched.ok) {
+        console.log("");
+        console.log(body(paint.faint(`Matched against the live catalogue - ${fetched.index.count} components.`)));
+    }
+    else {
+        console.log("");
+        console.log(body(describeFallback(fetched, floorSize())));
+    }
+    /**
+     * THE SIGNALS, said as EVIDENCE. "189 dark utilities across 30 files, bound to
+     * `[data-theme=dark]`, opening dark with the OS overruled" is something a person can
+     * confirm or correct; "this is a dark product" is a claim they take on faith.
+     */
+    const signalLines = describeSignals(signals);
+    if (signalLines.length > 0) {
+        console.log("");
+        console.log(section("What was countable, counted"));
+        for (const line of signalLines)
+            console.log(body(line));
+        console.log(body(paint.faint("Do not go looking for any of this - it is measured, and a sweep would bring back a different slice than the next one.")));
+    }
     const coverageLines = describeCoverage(coverage);
     if (coverageLines.length > 0) {
         console.log("");
@@ -751,14 +880,19 @@ export async function takeCensus(root, opts) {
     }));
     const pkgRaw = await readFile(join(root, "package.json"), "utf8").catch(() => null);
     let name = null;
+    /** Their pinned ranges, so a library signal cites the version rather than going stale. */
+    let versions = {};
     if (pkgRaw) {
         try {
-            name = JSON.parse(pkgRaw).name ?? null;
+            const pkg = JSON.parse(pkgRaw);
+            name = pkg.name ?? null;
+            versions = { ...pkg.devDependencies, ...pkg.dependencies };
         }
         catch {
             // an unreadable package.json costs the name, not the run
         }
     }
+    finishSignals(signals, importTally, versions);
     // Every name their CSS defines, from the same harvest the token table came
     // from - so a reference is judged against what actually exists, not against
     // the subset we managed to read as a ramp.
@@ -795,6 +929,7 @@ export async function takeCensus(root, opts) {
          * printed it, and never turned it into a rule is a feature that does nothing (dono,
          * 01/08).
          */
+        signals,
         ...(coverage.components > 0
             ? {
                 coverage: {

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
+import { readToken, resolveRegistry } from "../config.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { nearestToken, tokenFor } from "../doctor/tokens.js";
@@ -93,6 +94,29 @@ const TOOLS = [
             required: ["name"],
         },
     },
+    {
+        name: "recipe_vocabulary",
+        description: "What a recipe CAN hold: every state that compiles, every preview form, the floor per kind, and the rules a media region needs. Call this BEFORE writing a recipe, not after - the reader that skipped it sent a `dark:` inside a variant and a state the compiler cannot spell, and both were dropped in silence. Served from the catalogue, so it grows as the contract grows.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "validate_recipe",
+        description: "Would this recipe survive being sent? Answers with what would NOT - the properties held by the schema and dropped by the compiler, and what is missing before it can be drawn at all - by name, with the reason. Never a boolean: a boolean tells you to try again, a list tells you what to fix. Call it on every recipe before sending, and write what it returns into `_synthesisui/not-expressed.md`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "The component name, for the report.",
+                },
+                recipe: {
+                    type: "object",
+                    description: "The candidate recipe, in the document's own shape.",
+                },
+            },
+            required: ["recipe"],
+        },
+    },
     {
         name: "request_component",
         description: "File a component request when nothing in the catalogue covers what you need. This is the OTHER HALF of the refusal rule: you already say which entry you considered and why it did not fit - said in chat, that reasoning evaporates; filed here, it becomes the queue the system's author works from. File it at the moment you build the workaround, while the reasoning is still yours.",
@@ -217,6 +241,126 @@ async function listComponents(root) {
  * back says what the platform UNDERSTOOD - so a reading that came out thin is
  * visible instead of being discovered later in a preview.
  */
+/**
+ * WHAT A RECIPE CAN HOLD - served, not written here.
+ *
+ * The reader had no way to ask, so it sent what it found and the parts we could not hold
+ * were dropped in silence: a state the compiler cannot spell, a `dark:` inside a variant,
+ * a part name with a dot in it. Four times in one day (dono, 01/08).
+ *
+ * Fetched rather than embedded, and the owner's reason is the one that decides it: "the
+ * properties need to be dynamic - the more we map, the more precision". A list written
+ * into a published package is a list that stops matching the contract.
+ */
+async function recipeVocabulary() {
+    const answer = await askCatalogue("vocabulary");
+    if (!answer.ok)
+        return answer.because;
+    const v = answer.body;
+    const lines = [
+        "WHAT A RECIPE CAN HOLD",
+        "",
+        `properties: any CSS property, camelCase. Part names match ${v.partName} - flat and kebab-case, because a nested name compiles to two classes and is invalid CSS.`,
+        "",
+        `states that compile (${v.states.length}): ${v.states.join(", ")}`,
+        `preview forms: ${v.forms.join(", ")}`,
+        `a layer's conditions: ${v.layerConditions.join(", ")} - and they combine, so a ghost button's hover at the md breakpoint is one layer`,
+        "",
+        "THE FLOOR - below this a preview cannot be told apart from the page:",
+        ...Object.entries(v.floor).map(([kind, needs]) => `  ${kind}: ${needs.join("; ")}`),
+        "",
+        "WHAT TO GO LOOK FOR, per kind - work the list and say which ones their code answers:",
+        ...Object.entries(v.checklist).map(([kind, items]) => `  ${kind}:\n${items.map((i) => `    - ${i}`).join("\n")}`),
+        "",
+        "A MEDIA REGION cannot be used without these, and four of the five are about what happens when the picture is not there:",
+        ...v.media.map((m) => `  ${m.need} - ${m.why}`),
+    ];
+    return lines.join("\n");
+}
+/**
+ * WOULD THIS RECIPE SURVIVE? - the handshake that makes a loss visible when it happens.
+ *
+ * Nothing validated a recipe before it was sent: zero mentions of `validate` in the entire
+ * import path. So the reader sent, the document held half of it, and nobody noticed until
+ * somebody looked at a blank component weeks later.
+ */
+async function validateRecipe(name, recipe) {
+    const answer = await askCatalogue("validate", { name, recipe });
+    if (!answer.ok)
+        return answer.because;
+    const v = answer.body;
+    if (v.ok) {
+        return `${name}: everything you sent would survive. Send it.`;
+    }
+    const lines = [`${name}: this would NOT arrive whole.`, ""];
+    if (v.rejected.length > 0) {
+        lines.push("REFUSED by the contract - fix these or the whole recipe is dropped:");
+        for (const r of v.rejected)
+            lines.push(`  ${r.at}: ${r.why}`);
+        lines.push("");
+    }
+    if (v.lost.length > 0) {
+        lines.push("HELD BY THE SCHEMA AND DROPPED BY THE COMPILER - the silent half, which is the", "one worth fixing before sending:");
+        for (const l of v.lost)
+            lines.push(`  ${l}`);
+        lines.push("");
+    }
+    if (v.missing.length > 0) {
+        lines.push("BELOW THE FLOOR - it would arrive and not be drawable:");
+        for (const m of v.missing)
+            lines.push(`  ${m}`);
+        lines.push("");
+    }
+    if (v.checklist.length > 0) {
+        lines.push("Go looking for these before you send it again:");
+        for (const c of v.checklist)
+            lines.push(`  - ${c}`);
+    }
+    lines.push("", "Write this into `_synthesisui/not-expressed.md` - what we cannot hold is the list", "the system's author works from, and said only in chat it evaporates.");
+    return lines.join("\n");
+}
+/**
+ * The catalogue's door, with the session the device login already granted.
+ *
+ * Served rather than shipped for the two reasons the owner gave (dono, 01/08): a table in
+ * a published package can be read by anyone, and it goes stale - the crosswalk's own copy
+ * had 26 names against a catalogue of 41.
+ */
+async function askCatalogue(want, post) {
+    const token = await readToken();
+    if (!token) {
+        return {
+            ok: false,
+            because: "Not signed in, so the catalogue could not answer. Run `synthesisui login` in the terminal and call this again - this one needs a session, unlike `doctor`.",
+        };
+    }
+    const base = resolveRegistry();
+    try {
+        const res = await fetch(`${base}/api/catalogue${post ? "" : `?want=${want}`}`, post
+            ? {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(post),
+            }
+            : { headers: { Authorization: `Bearer ${token}` } });
+        if (!res.ok) {
+            return {
+                ok: false,
+                because: `The catalogue answered ${res.status}. ${res.status === 401 ? "Run `synthesisui login` and try again." : "Nothing was sent."}`,
+            };
+        }
+        return { ok: true, body: await res.json() };
+    }
+    catch {
+        return {
+            ok: false,
+            because: "No network, so the catalogue could not answer. Everything else in this server works offline; this one does not, and pretending otherwise would mean answering from a stale copy.",
+        };
+    }
+}
 async function describeComponent(root, name) {
     const { documents, requires } = await loadSystem(root);
     let recipe;
@@ -337,6 +481,10 @@ async function callTool(root, name, args) {
             return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
             return text(await addComponent(root, String(args.name ?? "")));
+        case "recipe_vocabulary":
+            return text(await recipeVocabulary());
+        case "validate_recipe":
+            return text(await validateRecipe(String(args.name ?? "this component"), args.recipe));
         case "request_component": {
             const r = await fileRequest(root, {
                 kind: "component",

package/dist/doctor/call-sites.js

@@ -49,12 +49,25 @@ const SPREAD_ONTO = /\{\s*\.\.\.\s*([A-Za-z_$][\w$]*)\s*\}/g;
  */
 export function readDefinitionProps(name, source) {
     const explicit = [];
+    const defaults = {};
     let restName = null;
+    /**
+     * EXACT NAME FIRST, THEN THE forwardRef SPELLING.
+     *
+     * `export const Label = forwardRef(LabelComponent)` defines its props on
+     * `LabelComponent`, and searching for `Label` alone read past the destructure - so a
+     * real Label's `variant = "body-md"` default never travelled (probe, 01/08). A prefix
+     * match (`LabelComponent` starts with `Label`) is the deterministic version of that
+     * idiom, and the exact name still wins when both exist.
+     */
     DESTRUCTURED.lastIndex = 0;
-    for (const m of source.matchAll(DESTRUCTURED)) {
+    const matches = [...source.matchAll(DESTRUCTURED)];
+    const exact = matches.filter((m) => (m[1] ?? m[3]) === name);
+    const prefixed = matches.filter((m) => {
         const found = m[1] ?? m[3];
-        if (found !== name)
-            continue;
+        return found !== name && found?.startsWith(name);
+    });
+    for (const m of exact.length > 0 ? exact : prefixed) {
         const body = m[2] ?? m[4] ?? "";
         for (const raw of body.split(",")) {
             const part = raw.trim();
@@ -69,6 +82,11 @@ export function readDefinitionProps(name, source) {
             if (/^[a-zA-Z_$][\w$]*$/.test(prop) && !explicit.includes(prop)) {
                 explicit.push(prop);
             }
+            // `variant = "body-md"` - the resting option, said by the definition itself.
+            // Only a string literal: a computed default is not in the source.
+            const def = /=\s*["']([^"']+)["']\s*$/.exec(part);
+            if (def && /^[a-zA-Z_$][\w$]*$/.test(prop))
+                defaults[prop] = def[1];
         }
         break;
     }
@@ -82,7 +100,7 @@ export function readDefinitionProps(name, source) {
             }
         }
     }
-    return { explicit, forwards };
+    return { explicit, defaults, forwards };
 }
 /**
  * WHICH COMPONENTS APPEAR INSIDE THIS ONE, at its call sites.

package/dist/doctor/catalogue-fetch.js

@@ -0,0 +1,88 @@
+/**
+ * THE CATALOGUE, FETCHED - because a table written into a published package goes stale
+ * and can be read by anyone.
+ *
+ * The crosswalk's own copy was written by hand and had 26 names against a catalogue of 41
+ * (dono, 01/08). Twenty of OUR OWN components were invisible to matching - `Textarea`,
+ * `Sidebar`, `Menu`, `Stepper`, `EmptyState` and fifteen more - and five names in it no
+ * longer existed. Their `Textarea` did not match our `textarea`. At 300 components that
+ * gap is 280, and closing it by hand means a version bump and a publish for every
+ * component we add. That was forgotten twice in one day.
+ *
+ * THE FLOOR STAYS. The written table is not deleted: it is what answers when there is no
+ * session and no network, which is a real state a person can be in. What changes is that
+ * it stops being the truth and starts being the fallback - and the run SAYS when it fell
+ * back, with the number that costs, because a silently smaller answer is the thing this
+ * whole pipeline keeps being punished for.
+ */
+import { readToken, resolveRegistry } from "../config.js";
+/**
+ * One call, at the start of a run.
+ *
+ * Not per component: a handshake for each of 362 components would be 362 round trips to
+ * answer a question one table answers. The index is 60 tokens a component and the caller
+ * matches locally against it.
+ */
+export async function fetchCatalogue(registryFlag) {
+    const token = await readToken();
+    if (!token) {
+        return {
+            ok: false,
+            why: "no-session",
+            because: "no session, so the catalogue could not be fetched - `synthesisui login` and re-run to match against the full list",
+        };
+    }
+    const base = resolveRegistry(registryFlag);
+    try {
+        const res = await fetch(`${base}/api/catalogue?want=index`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            return {
+                ok: false,
+                why: res.status === 401 ? "no-session" : "refused",
+                because: res.status === 401
+                    ? "the session was refused - `synthesisui login` and re-run"
+                    : `the catalogue answered ${res.status}`,
+            };
+        }
+        const index = (await res.json());
+        if (!Array.isArray(index?.components)) {
+            return {
+                ok: false,
+                why: "refused",
+                because: "the catalogue answered in a shape this version does not know",
+            };
+        }
+        return { ok: true, index };
+    }
+    catch {
+        return {
+            ok: false,
+            why: "offline",
+            because: "no network, so the catalogue could not be fetched",
+        };
+    }
+}
+/**
+ * The fetched index as the crosswalk's own table: canonical name → the words it answers
+ * to, plus the axes, which is what `axisOverlap` compares against.
+ */
+export function asCatalogueTable(index) {
+    const synonyms = {};
+    const axes = {};
+    for (const entry of index.components) {
+        synonyms[entry.name] = entry.also;
+        axes[entry.name] = entry.axes;
+    }
+    return { synonyms, axes };
+}
+/**
+ * What falling back COST, said with the number.
+ *
+ * "20 of our own components could not be matched" is a sentence somebody can act on;
+ * "using the built-in list" is not.
+ */
+export function describeFallback(result, floorSize) {
+    return `${result.because}. Matching used the ${floorSize} names built into this CLI instead of the live catalogue, so a component of yours that lines up with something we added recently will read as exclusively yours. That is a smaller answer, not a wrong one - re-run with a session to get the full one.`;
+}

package/dist/doctor/component-gate.js

@@ -136,6 +136,35 @@ function adapterFor(source, internal) {
     }
     return seen > 0 ? theirs : null;
 }
+/**
+ * HOW MANY SCREENS USE IT - the question that separates a design system from a folder.
+ *
+ * The gate took a real app from 704 to 271, and 271 names in a vitrine is the same
+ * problem with different numbers. `RegisterMultipleCSV`, `FeatureFlagUpdateForm`,
+ * `BoxHeaderInfo`, `SendProgressModal` are exclusive, correctly gated, and not design
+ * system: they are pieces of one screen.
+ *
+ * Enumerated before it was built, which is why the threshold is what it is (dono, 01/08):
+ *
+ *      42  used on NO screen        BoxHeaderInfo, Register, Search, Switcher
+ *     200  used on ONE screen       FeatureFlagUpdateForm, RegisterMultipleCSV
+ *      20  used on two screens      SkeletonLoader, Group, Header, UploadButton
+ *       2  used on three            ConfirmButton, Box
+ *       7  used on four or more     Table, Tag, Tooltip, Button, Loader
+ *
+ * 242 of 271 (89%) live on one screen or none. Filtering them takes the vitrine from 271
+ * to 29 - and the 29 are `Table`, `Tag`, `Tooltip`, `Button`, `Loader`, `Header`, which is
+ * what a design system is.
+ *
+ * TWO SCREENS IS THE LINE, and the distribution is why: the drop from 200 to 20 happens
+ * exactly there. A component two screens share is a decision about the product; a
+ * component one screen has is that screen's own markup.
+ *
+ * NOT APPLIED TO A LIBRARY. A library composes nothing inside itself, so every export
+ * would read as used on no screen - the same mistake library mode was built to stop. The
+ * caller passes the counts only when it has them, and absent means the test is skipped.
+ */
+export const SCREENS_FOR_SYSTEM = 2;
 export function gateComponent(input) {
     const { name, file, source } = input;
     if (RESERVED_FILE.test(file) || RESERVED_FILE_OTHER.test(file)) {
@@ -174,6 +203,15 @@ export function gateComponent(input) {
             because: `\`${name}\` is a capitalised export in a file with no markup - a constant, a config object or a helper`,
         };
     }
+    if (input.screens != null && input.screens < SCREENS_FOR_SYSTEM) {
+        return {
+            ok: false,
+            why: "feature",
+            because: input.screens === 0
+                ? `\`${name}\` is composed on no screen at all - it is a piece of markup nothing reaches yet`
+                : `\`${name}\` is composed on one screen only, so it is that screen's own markup rather than a decision the product shares. Two screens is the line, and the count is from your files`,
+        };
+    }
     if (!HAS_STYLING.test(source)) {
         return {
             ok: false,
@@ -195,6 +233,7 @@ export const SKIP_LABEL = {
     screen: "whole screens, and the frames around them",
     provider: "providers, contexts and wrappers",
     adapter: "adapters for another library's components",
+    feature: "pieces of one screen, not of the system",
     config: "constants, config and helpers",
     "no-jsx": "capitalised exports with no markup",
     "no-styling": "components that decide nothing about how anything looks",
@@ -204,6 +243,7 @@ export function groupSkips(skips) {
         "screen",
         "route",
         "provider",
+        "feature",
         "adapter",
         "no-styling",
         "config",

package/dist/doctor/crosswalk.js

@@ -155,17 +155,90 @@ const AXIS_SYNONYM = {
     placement: "side",
     position: "side",
 };
+/**
+ * THE LIVE TABLE, when a run fetched one.
+ *
+ * Module-level and set once per run, so every call site gets the same answer without
+ * threading the table through nine functions that do not care about it. Absent means the
+ * written `SYNONYM` floor answers - which is a smaller answer, and the run says so.
+ *
+ * The written table had 26 names against a catalogue of 41: twenty of our own components
+ * could not be matched at all (dono, 01/08). It stays as the offline floor, not as truth.
+ */
+let live = null;
+export function useLiveCatalogue(table) {
+    live = table;
+}
+/** How many names the written floor knows - the number a fallback message needs. */
+export function floorSize() {
+    return new Set(Object.values(SYNONYM)).size;
+}
 export function canonicalName(name) {
     const head = name
         .split(".")[0]
         .toLowerCase()
         .replace(/[^a-z]/g, "");
+    /**
+     * The live catalogue first, and its own name counts as a synonym for itself: their
+     * `Textarea` matching our `textarea` needed nothing clever, only a table that knew
+     * `textarea` exists.
+     */
+    if (live) {
+        for (const [canonical, also] of Object.entries(live.synonyms)) {
+            const words = [canonical, ...also].map((w) => w.replace(/[^a-z]/g, ""));
+            if (words.includes(head))
+                return canonical;
+        }
+    }
     if (SYNONYM[head])
         return SYNONYM[head];
     // A compound like `WidgetCard` or `ArrowDownIcon` is only canonical when the
     // WHOLE word is - a widget card is not a card, it is their own thing.
     return null;
 }
+/** The head of a name, the way `canonicalName` reads it. */
+function headOf(name) {
+    return name
+        .split(".")[0]
+        .toLowerCase()
+        .replace(/[^a-z]/g, "");
+}
+/**
+ * The canonical, kept only when the match is an identity or the axes back it up.
+ * See the note at the call site - this is the guard, not the policy.
+ */
+export function evidencedCanonical(component) {
+    const canonical = canonicalName(component.name);
+    if (!canonical)
+        return null;
+    // The name IS ours, spelled their way. `Text → text`, `Card → card`.
+    if (headOf(component.name) === canonical.replace(/-/g, ""))
+        return canonical;
+    // A synonym hop. Without live axes there is no evidence to weigh - old behaviour.
+    const target = live?.axes[canonical];
+    if (!target || Object.keys(target).length === 0)
+        return canonical;
+    // Their side has to DECLARE something for the disagreement to mean anything: a
+    // component with no axes offers no witness either way, and the name stands.
+    const theirOptions = new Set();
+    for (const values of Object.values(component.props)) {
+        for (const v of canonicalValues(values))
+            theirOptions.add(v);
+    }
+    if (theirOptions.size < 2)
+        return canonical;
+    const ourOptions = new Set();
+    for (const values of Object.values(target)) {
+        for (const v of canonicalValues(values))
+            ourOptions.add(v);
+    }
+    if (ourOptions.size === 0)
+        return canonical;
+    for (const v of theirOptions)
+        if (ourOptions.has(v))
+            return canonical;
+    return null;
+}
 export function canonicalAxes(props) {
     const out = new Set();
     for (const p of Object.keys(props)) {
@@ -368,7 +441,26 @@ opts) {
                     : "renders no UI - infrastructure, not a component",
             };
         }
-        const canonical = canonicalName(component.name);
+        /**
+         * A SYNONYM HOP NEEDS EVIDENCE; an identity match does not.
+         *
+         * `label → badge` was decided by the written table on the NAME alone, and their
+         * Label is a typography ladder - `variant: display|h1|h2|h3|body-sm|body-md|
+         * caption` - with nothing of a badge about it (dono, 01/08, "erros de match").
+         * Their `Text → text` is a different kind of claim: the name IS ours, spelled
+         * their way, and needs no second witness.
+         *
+         * So: a canonical reached through a synonym only stands when the axes agree -
+         * some shared option value (canonicalised, so `destructive` meets `danger`) with
+         * what the LIVE catalogue says that component offers. Their Tag's
+         * `color(danger|success|warning|neutral…)` overlaps our badge's intent options
+         * and survives; Label's heading ladder overlaps nothing and falls back to being
+         * exclusively theirs, which is what it was.
+         *
+         * Offline the live axes are absent and the old behaviour stands - the fallback
+         * message already says the answer is smaller.
+         */
+        const canonical = evidencedCanonical(component);
         const twins = mine
             .filter((o) => o.name !== component.name)
             .map((o) => ({
@@ -379,7 +471,10 @@ opts) {
             sharedCount(component.props, mine.find((m) => m.name === t.name)?.props ?? {}) >= TWIN_MIN_SHARED &&
             sharedMeaning(component.props, mine.find((m) => m.name === t.name)?.props ?? {}) >= 1)
             .sort((a, b) => b.overlap - a.overlap);
-        if (canonical && CATALOGUE[canonical]) {
+        // The LIVE catalogue counts as knowing the name: gating on the written table
+        // meant a component matched by the live one fell through to `nearly` (the same
+        // staleness, one branch down).
+        if (canonical && (CATALOGUE[canonical] || live?.axes[canonical])) {
             const alsoClaiming = (claims.get(canonical) ?? []).filter((n) => n !== component.name);
             /**
              * LIBRARY MODE: the match is a NOTE, not a verdict.

package/dist/doctor/signals.js

@@ -0,0 +1,286 @@
+/**
+ * WHAT IS COUNTABLE, COUNTED - so the reader decides instead of searching.
+ *
+ * The skill's theme section said "go and look" and listed five places to grep. Watching a
+ * real run, the agent swept for `framer-motion`, `lucide-react` and `@base-ui` too - things
+ * the skill never asked for - because "go and look" is an open invitation (dono, 01/08).
+ *
+ * Searching is expensive for three reasons that compound: every grep is a tool call, its
+ * whole output lands in the context, and the output is mostly noise - a `grep -rn "dark:"`
+ * over 2797 files returns hundreds of lines to answer a question that is one number.
+ *
+ * And it is worse than expensive: it is NOT DETERMINISTIC. Two readers sweeping the same
+ * repo bring back different slices, so the answer changes between runs.
+ *
+ * THE PRACTICE, and it holds for any system: give a reader the EVIDENCE and ask it to
+ * decide; never give it a question and ask it to search. Everything here is one more pass
+ * over files the census already walks - free on this side, and it deletes a handful of tool
+ * calls from the other.
+ *
+ * What is left for a person to judge after this is short and named: which grey is the page,
+ * what the product IS, and the anatomy of each component. Those are readings, not counts.
+ */
+/** A dark utility in a class name: `dark:bg-x`, and the `dark:` inside a longer chain. */
+const DARK_UTILITY = /(?:^|["'\s:])dark:/g;
+/** How a project says which theme is on. Ordered: the first hit is the one it uses. */
+const THEME_LIBRARY = [
+    [/from\s+["']next-themes["']/, "next-themes"],
+    [/from\s+["']@radix-ui\/themes["']/, "@radix-ui/themes"],
+    [/from\s+["']styled-components["'][\s\S]*ThemeProvider/, "styled-components"],
+    [/\buseColorScheme\b/, "react-native / useColorScheme"],
+    [/\bThemeProvider\b/, "a ThemeProvider of their own"],
+];
+/** `attribute="data-theme"` on the provider - the selector every dark rule then needs. */
+const THEME_ATTRIBUTE = /attribute\s*=\s*\{?["']([^"']+)["']/;
+/** `defaultTheme="dark"` - which face it opens in, said by the provider itself. */
+const DEFAULT_THEME = /defaultTheme\s*=\s*\{?["'](light|dark|system)["']/;
+/** `enableSystem={false}` - whether the OS gets a vote. */
+const ENABLE_SYSTEM = /enableSystem\s*=\s*\{(true|false)\}/;
+/** What `<html>` carries by default, which is what a dark rule matches against. */
+const HTML_ATTRS = /<html\b([^>]*)>/;
+const PACKAGE_FAMILIES = [
+    {
+        family: "motion",
+        test: /^(framer-motion|motion|@react-spring\/.+|gsap|popmotion|react-transition-group)$/,
+    },
+    {
+        family: "icons",
+        test: /^(lucide-react|react-icons|@heroicons\/react|@tabler\/icons-react|@phosphor-icons\/react|react-feather)$/,
+    },
+    {
+        family: "primitives",
+        test: /^(@radix-ui\/.+|@base-ui\/.+|@base-ui-components\/.+|@headlessui\/react|@ariakit\/react|@reach\/.+)$/,
+    },
+    {
+        family: "styling",
+        test: /^(class-variance-authority|tailwind-variants|clsx|tailwind-merge|styled-components|@emotion\/.+|@chakra-ui\/.+|@mui\/.+|@pandacss\/dev)$/,
+    },
+    {
+        family: "charts",
+        test: /^(recharts|victory|@nivo\/.+|chart\.js|react-chartjs-2|apexcharts|d3)$/,
+    },
+    {
+        family: "editors",
+        test: /^(@tiptap\/.+|slate|quill|react-quill|@lexical\/.+|lexical)$/,
+    },
+];
+export function emptySignals() {
+    return {
+        theme: {
+            darkUtilities: 0,
+            darkFiles: 0,
+            library: null,
+            attribute: null,
+            defaultTheme: null,
+            enableSystem: null,
+            prefersColorScheme: 0,
+            htmlCarries: [],
+        },
+        libraries: [],
+        conflicts: [],
+    };
+}
+const ANY_IMPORT = /(?:from\s+["']([^"'.][^"']*)["']|require\(\s*["']([^"'.][^"']*)["']\s*\))/g;
+/** The package a specifier belongs to: `@tiptap/react` and `motion/react` both keep the
+ *  part a manifest would name. */
+export function packageOf(specifier) {
+    if (specifier.startsWith("@")) {
+        const parts = specifier.split("/");
+        return parts.slice(0, 2).join("/");
+    }
+    return specifier.split("/")[0];
+}
+/**
+ * THE LIBRARY a package belongs to, which is not the same as the package.
+ *
+ * `@tiptap/react`, `@tiptap/starter-kit` and nineteen extensions are ONE library, and
+ * reporting them as twenty-one entries and a conflict is noise pretending to be a finding
+ * (probe, 01/08). A scope is a library; an unscoped name is its own.
+ */
+export function libraryOf(specifier) {
+    const pkg = packageOf(specifier);
+    return pkg.startsWith("@") ? `${pkg.split("/")[0]}/*` : pkg;
+}
+/**
+ * Fold one file into the signals. Called from the walk the census already does, so nothing
+ * here costs a second pass over the disk.
+ */
+export function readSignalsInto(into, imports, file, source) {
+    const isCode = /\.(tsx|jsx|ts|js|mjs|cjs|vue|svelte)$/i.test(file);
+    const isStyle = /\.(css|scss|sass|less)$/i.test(file);
+    if (isStyle) {
+        into.theme.prefersColorScheme += (source.match(/prefers-color-scheme/g) ?? []).length;
+        return;
+    }
+    if (!isCode)
+        return;
+    DARK_UTILITY.lastIndex = 0;
+    const dark = (source.match(DARK_UTILITY) ?? []).length;
+    if (dark > 0) {
+        into.theme.darkUtilities += dark;
+        into.theme.darkFiles += 1;
+    }
+    into.theme.prefersColorScheme += (source.match(/prefers-color-scheme/g) ?? []).length;
+    // The first library that matches wins, and the order is deliberate: an explicit
+    // dependency beats a `ThemeProvider` that could be anybody's.
+    if (!into.theme.library) {
+        for (const [test, name] of THEME_LIBRARY) {
+            if (test.test(source)) {
+                into.theme.library = name;
+                break;
+            }
+        }
+    }
+    into.theme.attribute ??= THEME_ATTRIBUTE.exec(source)?.[1] ?? null;
+    into.theme.defaultTheme ??= DEFAULT_THEME.exec(source)?.[1] ?? null;
+    if (into.theme.enableSystem === null) {
+        const enable = ENABLE_SYSTEM.exec(source);
+        if (enable)
+            into.theme.enableSystem = enable[1] === "true";
+    }
+    /**
+     * WHAT `<html>` CARRIES. Every dark rule in the project is written against this
+     * ancestor, so reading it is what turns "they have a dark theme" into "their dark rules
+     * match `[data-theme=dark]`, which is what ours must match too".
+     */
+    const html = HTML_ATTRS.exec(source);
+    if (html) {
+        for (const m of html[1].matchAll(/([a-zA-Z-]+)\s*=\s*(?:["']([^"']*)["']|\{["']([^"']*)["']\})/g)) {
+            const attr = `${m[1]}="${m[2] ?? m[3] ?? ""}"`;
+            if (!into.theme.htmlCarries.includes(attr)) {
+                into.theme.htmlCarries.push(attr);
+            }
+        }
+    }
+    ANY_IMPORT.lastIndex = 0;
+    const seen = new Set();
+    for (const m of source.matchAll(ANY_IMPORT)) {
+        const spec = m[1] ?? m[2];
+        if (!spec)
+            continue;
+        const pkg = packageOf(spec);
+        // `motion/react` and `motion` are one package, and a file importing both is one file.
+        const key = /^motion(\/|$)/.test(spec) ? spec : pkg;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        imports.set(key, (imports.get(key) ?? 0) + 1);
+    }
+}
+/**
+ * The libraries, and the conflicts, from the import tally and their manifest.
+ *
+ * `versions` is `dependencies` merged with `devDependencies`, so the rule can cite the
+ * range they pinned rather than going stale the day they upgrade.
+ */
+export function finishSignals(into, imports, versions) {
+    const byFamily = new Map();
+    for (const [name, files] of imports) {
+        const pkg = packageOf(name);
+        const family = PACKAGE_FAMILIES.find((f) => f.test.test(pkg) || f.test.test(name));
+        if (!family)
+            continue;
+        const version = versions[pkg] ?? versions[name];
+        const signal = {
+            family: family.family,
+            name,
+            files,
+            ...(version ? { version } : {}),
+        };
+        byFamily.set(family.family, [
+            ...(byFamily.get(family.family) ?? []),
+            signal,
+        ]);
+    }
+    /**
+     * COLLAPSED BY LIBRARY. Twenty-one `@tiptap/*` entries answer nothing a person wanted to
+     * know; `@tiptap/* (21 packages, 4 files)` answers it in one line. The file count is the
+     * WIDEST of the group rather than the sum: four files import tiptap, not fifty-two.
+     */
+    into.libraries = [...byFamily.entries()]
+        .flatMap(([family, signals]) => {
+        const byLibrary = new Map();
+        for (const signal of signals) {
+            const key = libraryOf(signal.name);
+            byLibrary.set(key, [...(byLibrary.get(key) ?? []), signal]);
+        }
+        return [...byLibrary.entries()].map(([library, group]) => ({
+            family,
+            name: group.length > 1 ? library : group[0].name,
+            files: Math.max(...group.map((g) => g.files)),
+            ...(group.length > 1 ? { packages: group.length } : {}),
+            ...(group[0].version ? { version: group[0].version } : {}),
+        }));
+    })
+        .sort((a, b) => b.files - a.files || a.name.localeCompare(b.name));
+    /**
+     * TWO IN ONE FAMILY IS A FINDING. `framer-motion` in four files and `motion/react` in
+     * three, in one package, is the same library under two names and one of them is dead
+     * weight in the bundle. A person should see it; we do not decide it.
+     *
+     * `styling` and `primitives` are exempt: `clsx` beside `tailwind-merge` is the normal
+     * pairing, and two primitive libraries in a large app is a migration in progress, not a
+     * mistake.
+     */
+    for (const [family, signals] of byFamily) {
+        if (family === "styling" || family === "primitives")
+            continue;
+        // By LIBRARY, not by package: `@tiptap/react` beside `@tiptap/starter-kit` is one
+        // library used correctly, and calling it a conflict was noise (probe, 01/08).
+        const names = [...new Set(signals.map((x) => libraryOf(x.name)))];
+        if (names.length > 1)
+            into.conflicts.push({ family, names });
+    }
+    return into;
+}
+/**
+ * The signals as the sentences the reader would otherwise have gone looking for.
+ *
+ * Written as EVIDENCE rather than as a verdict: "189 dark utilities across 30 files, bound
+ * to `[data-theme=dark]`, opening dark with the OS overruled" is something a person can
+ * confirm or correct. "This is a dark product" is a claim they have to take on faith.
+ */
+export function describeSignals(s) {
+    const out = [];
+    const t = s.theme;
+    if (t.darkUtilities > 0) {
+        out.push(`${t.darkUtilities} dark utilities across ${t.darkFiles} file${t.darkFiles === 1 ? "" : "s"} - so a second scheme is real here, not aspirational.`);
+    }
+    else if (t.prefersColorScheme > 0) {
+        out.push(`no dark utilities, but ${t.prefersColorScheme} \`prefers-color-scheme\` rule${t.prefersColorScheme === 1 ? "" : "s"} - the second scheme lives in CSS rather than in class names.`);
+    }
+    else {
+        out.push("no dark utilities and no `prefers-color-scheme` - one scheme, and adding a second is a decision rather than a discovery.");
+    }
+    if (t.library) {
+        const bits = [`switched by ${t.library}`];
+        if (t.attribute)
+            bits.push(`bound to \`${t.attribute}\``);
+        if (t.defaultTheme)
+            bits.push(`opening ${t.defaultTheme}`);
+        if (t.enableSystem === false)
+            bits.push("with the OS overruled");
+        if (t.enableSystem === true)
+            bits.push("with the OS allowed a vote");
+        out.push(`${bits.join(", ")}.`);
+    }
+    if (t.htmlCarries.length > 0) {
+        out.push(`\`<html>\` carries ${t.htmlCarries.map((a) => `\`${a}\``).join(" ")} - which is the ancestor every dark rule of theirs matches, and therefore the one ours must match.`);
+    }
+    for (const family of ["primitives", "motion", "icons", "charts", "editors"]) {
+        const found = s.libraries.filter((l) => l.family === family);
+        if (found.length === 0)
+            continue;
+        out.push(`${family}: ${found.map((l) => `${l.name}${l.version ? ` ${l.version}` : ""} (${l.packages ? `${l.packages} packages, ` : ""}${l.files} file${l.files === 1 ? "" : "s"})`).join(", ")}`);
+    }
+    for (const c of s.conflicts) {
+        // The count is read off the list rather than written into the sentence: it said "TWO"
+        // over three names, which is the kind of small lie that costs the next sentence its
+        // credibility (probe, 01/08).
+        const list = c.names.length === 2
+            ? c.names.join(" and ")
+            : `${c.names.slice(0, -1).join(", ")} and ${c.names[c.names.length - 1]}`;
+        out.push(`${c.names.length} ${c.family} LIBRARIES: ${list}. The same job under more than one name, and the extras are weight in the bundle for nothing. Worth your attention; not ours to decide.`);
+    }
+    return out;
+}

package/dist/skill-import.js

@@ -237,13 +237,19 @@ This is the field that matters most and the one only you can fill. The ladder ca
 places no token reader sees. A real library declared nine near-blacks and five light greys in
 one \`:root\` block, and the import handed its near-black dashboard a white page.
 
-Go and look:
+**DO NOT GO LOOKING. It is already counted**, under "What was countable, counted" in the
+census output:
 
-- \`grep -rn "dark:" --include=*.tsx\` - Tailwind's dark variant, invisible to a token reader
-- a theme provider, \`useTheme\`, \`next-themes\`, a \`data-theme\` attribute, a toggle in the shell
-- \`prefers-color-scheme\` in the CSS
-- the root layout: what class or attribute does \`<html>\` or \`<body>\` carry by default
-- failing all of that, open the app's main page component and see what it paints
+\`\`\`
+782 dark utilities across 79 files - so a second scheme is real here, not aspirational.
+switched by a ThemeProvider of their own, bound to data-theme, opening dark, with the
+  OS overruled.
+html carries lang="en" data-theme="dark" - which is the ancestor every dark rule of
+  theirs matches, and therefore the one ours must match.
+\`\`\`
+
+That is a real run. Your job is to CONFIRM OR CORRECT it, not to reproduce it - and a sweep
+would bring back a different slice than the next one, which is the worse property of the two.
 
 \`has: ["dark"]\` on a dark-only product is the right answer. It is better than filling a light
 slot on their behalf, and it makes adding light a deliberate act they take later.
@@ -537,6 +543,49 @@ extensions are configured at construction, not toggled later
 of their manifest and attaches it (\`"^2.1.0 in packages/ui"\`), so the rule does not go stale the
 day they upgrade and the information is not lost either.
 
+### Ask what a recipe can hold, BEFORE you write one
+
+\`\`\`
+recipe_vocabulary          what a recipe CAN hold - states, forms, the floor per kind
+validate_recipe(name, r)   would this survive? what would NOT, by name
+\`\`\`
+
+Both are MCP tools on the \`synthesisui\` server. **Call \`recipe_vocabulary\` once, at the
+start**, and work from what it says rather than from what you remember - it is served from
+the live contract, so it is right about a state that was added last week and this file is
+not.
+
+Then **validate every recipe before you send it.** This is not a formality. Nothing checked
+a recipe before these tools existed, and four separate readings were lost in silence: a
+\`dark:\` inside a variant, a state the compiler cannot spell, a part name with a dot in it,
+a layer with an empty style. Each of those was correct work that arrived as nothing.
+
+\`validate_recipe\` never answers yes or no. It answers with what would not survive:
+
+\`\`\`
+REFUSED by the contract        fix it or the WHOLE recipe is dropped
+HELD BY THE SCHEMA AND         the silent half - it validates, it compiles to nothing.
+DROPPED BY THE COMPILER        This is the one worth fixing before sending.
+BELOW THE FLOOR                it would arrive and not be drawable
+\`\`\`
+
+### Write down what we could not hold
+
+Everything \`validate_recipe\` reports goes into \`_synthesisui/not-expressed.md\`, appended
+per component:
+
+\`\`\`
+## MetricCard
+- layers[2].when.scheme … (what the validator said, VERBATIM)
+- below the floor: a fill, so it reads as a surface rather than as bare text
+- the source you read, quoted, so the gap can be checked without opening their repo
+\`\`\`
+
+**Verbatim, and with the source beside it.** This file is how a gap on OUR side gets fixed
+instead of being worked around: said only in chat it evaporates, and paraphrased it becomes
+unfindable. If the file ends up empty, say so - that is the good outcome and it is worth
+one line.
+
 ### The floor: what a preview needs before it can draw anything
 
 The owner asked this directly - "to render the button, what do I need to have?" - and the
@@ -591,6 +640,16 @@ what shows when it is missing a missing asset must never look broken
 
 ### What the CLI now reads for you, so do not spend a turn on it
 
+**The rule under all of this: you are given EVIDENCE and asked to DECIDE.** You are never
+given a question and asked to search. A grep is a tool call whose entire output lands in your
+context to answer something that is one number, and two readers sweeping the same repo bring
+back different slices - so the answer changes between runs, which is the part that actually
+costs.
+
+Measured on a real run: the census counts the theme signals, the libraries and their
+versions, and the conflicts. The reader that swept for them anyway spent a dozen shell calls
+to arrive at a subset of what was already on screen.
+
 Four things are read deterministically from the source. Reporting them back as if you
 found them wastes a turn and risks contradicting the measurement:
 
@@ -599,6 +658,13 @@ found them wastes a turn and risks contradicting the measurement:
 - **whether a component forwards the rest of its props**, and which it names
 - **which components appear inside which** at their call sites, as pairs
 - **the folder architecture**, and it will ask you which one has priority
+- **the theme**: how many dark utilities, in how many files, which library switches it, which
+  attribute it is bound to, what \`<html>\` carries, and how many \`prefers-color-scheme\` rules
+- **the libraries and their versions** - motion, icons, primitives, charts, editors - with the
+  file count for each, and a CONFLICT when one job is done by more than one of them
+- **which of your components are ours**, matched against the LIVE catalogue rather than a
+  list baked into the CLI. If a run says it fell back to the built-in names, the match is a
+  smaller answer than it should be and the reason is on screen
 
 What is still yours: the anatomy tree, the part names, the frontiers, the roles, the
 concept, and the rules that are not about a class name.

package/package.json

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