synthesisui 0.16.83 → 0.16.84

package/dist/commands/import.js

@@ -5,12 +5,13 @@ 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";
@@ -214,8 +215,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);
@@ -245,6 +274,12 @@ export async function takeCensus(root, opts) {
     const nesting = 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. */
@@ -299,6 +334,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({
@@ -440,6 +483,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 +758,14 @@ 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())));
+    }
     const coverageLines = describeCoverage(coverage);
     if (coverageLines.length > 0) {
         console.log("");

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/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,11 +155,41 @@ 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
@@ -379,7 +409,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/skill-import.js

@@ -537,6 +537,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
@@ -599,6 +642,9 @@ 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
+- **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.84",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {