synthesisui 0.16.79 → 0.16.80

package/dist/anatomy-read.js

@@ -30,7 +30,7 @@
  * of the three outcomes this pipeline has paid for twice.
  */
 import { transcribe, } from "./doctor/transcribe.js";
-/** The nine forms, closed. A renderer that accepts any tag draws anything. */
+/** The ten forms, closed. A renderer that accepts any tag draws anything. */
 const FORMS = new Set([
     "image",
     "heading",
@@ -42,6 +42,7 @@ const FORMS = new Set([
     "stack",
     "component",
     "external",
+    "slot",
 ]);
 /** The two that arrange, and the only two that take children. */
 const CONTAINERS = new Set(["row", "stack"]);
@@ -198,6 +199,19 @@ root) {
             const text = typeof node.text === "string" ? node.text.trim() : "";
             if (text)
                 node_.text = text.slice(0, 120);
+            /**
+             * A SLOT KEEPS ITS STYLES AND BORROWS ITS CONTENT.
+             *
+             * Unlike the other two frontiers it is not somebody else's element - it IS
+             * theirs, and its border and hover belong on it. Only what goes inside is the
+             * caller's, so `expects` says what that is in their words instead of the
+             * preview drawing a blank.
+             */
+            if (as === "slot") {
+                const expects = typeof node.expects === "string" ? node.expects.trim() : "";
+                if (expects)
+                    node_.expects = expects.slice(0, 80);
+            }
             // Only the two arrangers descend. A leaf with children is a leaf that was
             // labelled wrongly, and its children would render nowhere.
             if (CONTAINERS.has(as) && Array.isArray(node.children)) {

package/dist/commands/import.js

@@ -1,4 +1,4 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
@@ -6,7 +6,7 @@ import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
-import { crosswalk, observedRules } from "../doctor/crosswalk.js";
+import { crosswalk, isLibrary, observedRules } from "../doctor/crosswalk.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
@@ -207,7 +207,8 @@ function distinctValues(d) {
     }
     return kept.sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
 }
-export async function takeCensus(root) {
+export async function takeCensus(root, opts) {
+    const scopeLabel = opts?.scopeLabel;
     const css = await harvestOwnCss(root);
     const table = buildTable({ css, source: "yours" });
     const schemes = parseSchemeBlocks(css);
@@ -260,6 +261,48 @@ export async function takeCensus(root) {
     }
     const d = diagnose(reports);
     const inventory = tallyToInventory(tally);
+    /**
+     * THE EVIDENCE PASS - a second walk that touches ONE reading.
+     *
+     * Only the tally. Not `css`, not `declaredValues`, not `looks`, not `defined`,
+     * not `reports`: an app's classes are choices made from a scale, and folding
+     * them into the census would put the average back where the declaration goes.
+     *
+     * Deliberately its own tally so the LIBRARY QUESTION is asked of the scope
+     * alone. Fold the app in first and every export has a count, `isLibrary` reads
+     * false, and the crosswalk starts substituting the components it was just
+     * taught to keep.
+     */
+    const usageTally = emptyTally();
+    const usageSeen = new Set();
+    /**
+     * THE SCOPE'S OWN PACKAGE NAME IS INTERNAL, always.
+     *
+     * An app importing the system says `import { Button } from "@acme/ui"`, and the
+     * alias reader finds that name by walking the workspace for sibling manifests. It
+     * usually does - but when it cannot, every component the app composes files as
+     * THIRD-PARTY and the evidence pass counts nothing. The scope is the system by
+     * definition, so its name never needs discovering.
+     */
+    const scopePkg = await readFile(join(root, "package.json"), "utf8")
+        .then((raw) => JSON.parse(raw).name ?? null)
+        .catch(() => null);
+    const shared = scopePkg ? [...internal, scopePkg] : internal;
+    for (const u of opts?.usage ?? []) {
+        const uInternal = await internalSpecifiers(u.path);
+        for await (const file of walk(u.path)) {
+            const src = await readFile(file, "utf8").catch(() => "");
+            if (!src)
+                continue;
+            const rel = join(u.label, relative(u.path, file));
+            if (/(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/.test(rel)) {
+                continue;
+            }
+            usageSeen.add(rel);
+            scanComponentsInto(usageTally, rel, src, [...shared, ...uInternal]);
+        }
+    }
+    const usedThere = tallyToInventory(usageTally, 400);
     /**
      * THE TWO READINGS BECOME ONE LIST before anything is judged.
      *
@@ -285,6 +328,9 @@ export async function takeCensus(root) {
             ...Object.fromEntries(d.flags.map((f) => [f, ["true"]])),
         },
         propFiles: {},
+        // Their own rung, off the folder. It travels from the DEFINITION because
+        // that is the only reading that knows which file the component lives in.
+        ...(d.tier ? { tier: d.tier } : {}),
     }));
     /**
      * A composed component that is ALSO defined keeps its usage and gains the
@@ -306,20 +352,104 @@ export async function takeCensus(root) {
     const declaredBy = new Map(defined.map((d) => [d.name, d]));
     const enriched = inventory.map((c) => {
         const d = declaredBy.get(c.name);
-        if (!d || Object.keys(d.axes).length === 0)
+        if (!d)
             return c;
-        return { ...c, declaredAxes: d.axes };
+        const tier = d.tier ? { tier: d.tier } : {};
+        if (Object.keys(d.axes).length === 0) {
+            return Object.keys(tier).length > 0 ? { ...c, ...tier } : c;
+        }
+        return { ...c, declaredAxes: d.axes, ...tier };
+    });
+    const scoped = [...enriched, ...fromTypes];
+    /**
+     * THE EVIDENCE, FOLDED IN - counts and chosen values, never new components.
+     *
+     * A component the app has and the system does not is the app's own, and adopting
+     * it here would make the system a union of two codebases. It is reported instead:
+     * a number somebody can act on beats a component nobody asked for.
+     *
+     * The counts ADD because they are the same act measured in two places, and the
+     * prop values union because both are things somebody typed. `propFiles` is what
+     * the laws read, and it is the reason this pass exists: three files agreeing is
+     * what makes a habit, and a library has one file per component.
+     */
+    const own = new Set(scoped.map((c) => c.name));
+    const evidence = new Map(usedThere.filter((c) => !c.from).map((c) => [c.name, c]));
+    const merged = scoped.map((c) => {
+        const e = evidence.get(c.name);
+        if (!e)
+            return c;
+        /**
+         * A COMPONENT COMPOSED NOWHERE IN THE SCOPE carries its DECLARATION in `props`,
+         * because for a library that is the only reading there is. The moment real usage
+         * arrives, that declaration has to move where declarations live - otherwise the
+         * two readings merge and `props` stops meaning "what the code passed".
+         *
+         * It is the same mistake `declaredAxes` exists to prevent, arriving from the
+         * other side: unioned, a Button declaring solid|ghost and only ever passed solid
+         * reports two options, and the law that all four files agree can never be
+         * written.
+         */
+        const declaredOnly = (c.count ?? 0) === 0;
+        const props = declaredOnly ? {} : { ...c.props };
+        for (const [prop, values] of Object.entries(e.props)) {
+            props[prop] = [...new Set([...(props[prop] ?? []), ...values])];
+        }
+        const declaredAxes = c.declaredAxes ?? (declaredOnly ? c.props : undefined);
+        const propFiles = { ...(c.propFiles ?? {}) };
+        for (const [prop, n] of Object.entries(e.propFiles ?? {})) {
+            propFiles[prop] = (propFiles[prop] ?? 0) + n;
+        }
+        return {
+            ...c,
+            count: (c.count ?? 0) + (e.count ?? 0),
+            files: (c.files ?? 0) + (e.files ?? 0),
+            props,
+            propFiles,
+            ...(declaredAxes && Object.keys(declaredAxes).length > 0
+                ? { declaredAxes }
+                : {}),
+        };
     });
-    const merged = [...enriched, ...fromTypes];
+    const theirsOnly = usedThere.filter((c) => !c.from && !own.has(c.name));
     // The verdict travels WITH the payload: the platform reads one reading rather
     // than computing a second opinion from the same numbers, which is how two
     // implementations of the same judgement start disagreeing.
-    const verdicts = new Map(crosswalk(merged).map((r) => [
+    /**
+     * IS THIS SCOPE A LIBRARY? The answer changes what the crosswalk is FOR.
+     *
+     * In an app, "your Pill reads as our badge" saves them a duplicate. In a library it
+     * would delete their component - and 16 of 37 in a real one were deleted that way
+     * (dono, 01/08). Measured, not guessed: a library declares and does not compose
+     * itself. See `isLibrary`.
+     */
+    const library = isLibrary(scoped);
+    const verdicts = new Map(crosswalk(merged, { library }).map((r) => [
         r.component.name,
         { bucket: r.bucket, canonical: r.canonical, because: r.because },
     ]));
+    if (usedThere.length > 0) {
+        console.log("");
+        console.log(body(`Read ${usageSeen.size} more file${usageSeen.size === 1 ? "" : "s"} for EVIDENCE only - ${(opts?.usage ?? []).map((u) => paint.strong(u.label)).join(", ")}. What comes from there is how often each component is used and which values get picked, which is what turns a settled choice into a law. The palette, the scales and the convention stay from ${paint.strong(scopeLabel ?? "the system")}: an app's average is not a scale, it is a set of choices made from one.`));
+        if (theirsOnly.length > 0) {
+            const shown = theirsOnly.slice(0, 6).map((c) => c.name);
+            console.log(body(paint.faint(`(${theirsOnly.length} component${theirsOnly.length === 1 ? "" : "s"} live there and not in the system - ${shown.join(", ")}${theirsOnly.length > shown.length ? ", …" : ""}. Left out on purpose: the system is one place, and a union of two codebases is not a system. Point --scope at them if they belong in it.)`)));
+        }
+    }
+    if (library) {
+        console.log("");
+        console.log(body(`This scope DECLARES its components and composes almost none of them inside itself - which is what a component library looks like from the inside. So every component it exports arrives as YOURS, with its own recipe. Where one reads like something in our catalogue, that is recorded as a note instead of replacing it.`));
+    }
+    /**
+     * THE LAWS READ THE MERGED LIST, not the scope's.
+     *
+     * `RULE_MIN_FILES` is three, and a library has one file per component - so
+     * measured against the scope alone, "every file that passes it agrees" can never
+     * be true and the habit rung stays empty forever. The app is where the agreeing
+     * happens, which is the whole reason `--usage` exists.
+     */
     const laws = new Map();
-    for (const r of observedRules(inventory)) {
+    for (const r of observedRules(merged)) {
         laws.set(r.component, [...(laws.get(r.component) ?? []), r.text]);
     }
     const components = merged.map((c) => ({
@@ -361,6 +491,9 @@ export async function takeCensus(root) {
         observed: distinctValues(d),
         ...(components.length > 0 ? { components } : {}),
         ...(defined.length > 0 ? { defined } : {}),
+        ...((opts?.usage ?? []).length > 0
+            ? { usage: (opts?.usage ?? []).map((u) => u.label) }
+            : {}),
         totals: {
             scanned: d.scanned,
             values: d.findings.length,
@@ -670,9 +803,22 @@ async function sayIfWorkspace(root) {
     console.log(body("That is a fine DIAGNOSIS and a poor system: a light app and a dark one"));
     console.log(body("average into a palette that is neither."));
     console.log("");
+    /**
+     * BOTH ROLES IN ONE LINE, because a person reading this has both folders open.
+     *
+     * `--scope` alone is where the library came back with no laws at all: the system
+     * is one place, but the EVIDENCE that a choice is settled is somewhere else, and
+     * naming only the first left the second unreachable (dono, 01/08).
+     */
+    const usageFlags = apps
+        .slice(0, 2)
+        .map((a) => `--usage ${a}`)
+        .join(" ");
     if (shared.length > 0) {
         console.log(body("The shape that works, if your vocabulary is shared:"));
-        console.log(body(`    ${paint.strong(`synthesisui import --scope ${shared[0]}`)}   ${paint.faint("the system comes from here")}`));
+        console.log(body(`    ${paint.strong(`synthesisui import --scope ${shared[0]} ${usageFlags}`)}`));
+        console.log(body(paint.faint(`      --scope is the SYSTEM: the tokens, the components, the way you name a class. One place.`)));
+        console.log(body(paint.faint(`      --usage is the EVIDENCE: how often each component is used and which values get picked. As many as you have.`)));
     }
     else {
         console.log(body("The shape that works:"));
@@ -1017,11 +1163,40 @@ export async function runImport(opts) {
      * decisions live in one package and the governance belongs at the root, and
      * conflating the two meant every re-measure scattered another census.
      */
-    const scope = opts.scope
-        ?.trim()
+    const tidy = (p) => p
+        .trim()
         .replace(/^\.\/+/, "")
         .replace(/\/+$/, "");
+    const scope = opts.scope ? tidy(opts.scope) : undefined;
     const readFrom = scope ? join(root, scope) : root;
+    /**
+     * THE SECOND ROLE. `--scope` is the SYSTEM - one place, and the only source of
+     * the palette, the scales and the convention. `--usage` is the EVIDENCE - as
+     * many places as they have, and the only source of counts, chosen values and
+     * laws.
+     *
+     * They were one flag, and one flag could only answer one of the two questions.
+     * Pointed at a real library, `usage` came back empty on all 23 components and
+     * the habit rung of the ladder was unreachable by construction: a law needs
+     * three files that agree and a library has one file per component (dono, 01/08).
+     */
+    const usage = [];
+    for (const raw of opts.usage ?? []) {
+        const label = tidy(raw);
+        if (!label || label === scope)
+            continue;
+        const path = join(root, label);
+        const ok = await stat(path)
+            .then((st) => st.isDirectory())
+            .catch(() => false);
+        if (!ok) {
+            console.log(section("Import"));
+            console.log(body(`\`--usage ${label}\` is not a folder under ${paint.strong(root)}. Nothing was read.`));
+            return;
+        }
+        if (!usage.some((u) => u.label === label))
+            usage.push({ path, label });
+    }
     // A census handed to us (an agent annotated it) is sent as-is; the numbers
     // inside were still ours to begin with.
     let census;
@@ -1060,7 +1235,10 @@ export async function runImport(opts) {
     }
     else {
         console.log(section("Reading your project"));
-        census = await takeCensus(readFrom);
+        census = await takeCensus(readFrom, {
+            ...(usage.length > 0 ? { usage } : {}),
+            ...(scope ? { scopeLabel: scope } : {}),
+        });
         if (scope)
             census.scope = scope;
     }

package/dist/commands/mcp.js

@@ -232,6 +232,15 @@ async function describeComponent(root, name) {
     const out = [
         `${name}${recipe.description ? ` - ${recipe.description}` : ""}`,
     ];
+    // THEIR OWN RUNG, when their repo has one. An agent about to compose this should
+    // know whether it is a primitive or a whole region before it starts.
+    if (recipe.tier) {
+        out.push(recipe.tier === "atom"
+            ? "An atom in your own ladder - nothing else in the system breaks down into it."
+            : recipe.tier === "molecule"
+                ? "A molecule in your own ladder - built out of your atoms, so reach for those inside it."
+                : "An organism in your own ladder - a whole region of a screen, so it is more likely to be composed than to be composed into.");
+    }
     // WHAT IT SITS ON. 17 of 23 components in a real library carry no surface of
     // their own, because the surface belongs to what they return.
     const p = recipe.preview;

package/dist/component-codegen.js

@@ -516,6 +516,7 @@ const FORM_TAG = {
     icon: { tag: "span" },
     row: { tag: "div" },
     stack: { tag: "div" },
+    slot: { tag: "div" },
 };
 /** Only these two arrange; the rest are leaves. */
 const ARRANGES = new Set(["row", "stack"]);
@@ -555,6 +556,16 @@ function emitTree(nodes, comp, indent) {
             lines.push(`${indent}{/* ${node.from} renders here - a third party's component, so its markup is theirs */}`);
             continue;
         }
+        // The caller's content, so the generated code takes it as a prop rather than
+        // inventing a sample. A slot that also carries styles keeps its part element
+        // around the children; a bare one is just `{children}`.
+        if (node.as === "slot") {
+            const inner = `{children}${node.expects ? ` {/* ${node.expects} */}` : ""}`;
+            lines.push(node.part
+                ? `${indent}<${comp}${pascal(node.part)}>${inner}</${comp}${pascal(node.part)}>`
+                : `${indent}${inner}`);
+            continue;
+        }
         if (!node.part) {
             // Pure structure with no styles of its own: keep the arrangement, skip the
             // element - a div that carries nothing is a div nobody needs.

package/dist/doctor/components-scan.js

@@ -13,17 +13,30 @@ const LITERAL_PROP = /([a-zA-Z][a-zA-Z0-9_-]*)\s*=\s*\{?\s*["']([^"']*)["']\s*\}
 /** `dense` with no value is a boolean prop set to true, and that IS a literal
  *  decision worth counting. */
 const BARE_PROP = /(^|\s)([a-z][a-zA-Z0-9_]*)(?=\s|$)/g;
+/**
+ * A KEYWORD IS NOT AN IDENTIFIER, and the difference decides whether a `<` opens
+ * an element. `return <Card>one</Card>` is a component; `useState<Foo>()` is a
+ * type argument. Both are preceded by a word.
+ *
+ * Prettier writes `return <Foo />;` on one line whenever it fits, so without this
+ * every short component written that way read as a generic and vanished from the
+ * inventory - which is how a spec for something else caught it.
+ */
+const JSX_BEFORE = /\b(return|case|default|await|yield|typeof|in|of|do|else|new)$/;
 /**
  * A generic in type position (`useState<Foo>()`, `Array<Item>`) is not an
  * element. The tell is what precedes the `<`: an identifier or a closing paren
- * means a type argument, while JSX follows `(`, `{`, `>`, a newline or nothing.
+ * means a type argument, while JSX follows `(`, `{`, `>`, a newline, a keyword or
+ * nothing.
  */
 function looksLikeType(source, at) {
     for (let i = at - 1; i >= 0; i--) {
         const c = source[i];
         if (c === " " || c === "\t")
             continue;
-        return /[A-Za-z0-9_)\]]/.test(c);
+        if (!/[A-Za-z0-9_)\]]/.test(c))
+            return false;
+        return !JSX_BEFORE.test(source.slice(Math.max(0, i - 11), i + 1));
     }
     return false;
 }
@@ -81,6 +94,56 @@ function importedNames(source, internal = []) {
     }
     return out;
 }
+/**
+ * Capitalised names a file BINDS ITSELF and does not export.
+ *
+ * `<Component>` and `<CustomLegend/>` both arrived in a real library's inventory as
+ * components of the system (dono, 01/08). Neither is one:
+ *
+ *     function Text({ as: Component = "p" })     // React's polymorphic idiom -
+ *                                                // `Component` is a prop rename
+ *     const CustomLegend = () => (…)             // a closure inside LineChart
+ *
+ * Capitalisation is React's rule for "not an html tag", which is not the same
+ * question as "is this a component the system offers". The test that separates them
+ * is REACHABILITY: a component of the system is either imported from somewhere or
+ * exported to somewhere. A name that only exists inside one function body is that
+ * function's private wiring, and giving it a recipe invents a component nobody can
+ * import.
+ *
+ * Local AND exported stays, of course - that is just a component defined where it
+ * is used.
+ */
+const BOUND = /(?:const|let|var|function|class)\s+([A-Z][A-Za-z0-9_]*)|[{,]\s*\w+\s*:\s*([A-Z][A-Za-z0-9_]*)\s*(?:=[^,}]*)?\s*[,}]/g;
+const EXPORTED_NAME = /export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var)\s+([A-Z][A-Za-z0-9_]*)|export\s+default\s+([A-Z][A-Za-z0-9_]*)|export\s*\{([^}]*)\}/g;
+export function localOnlyNames(source) {
+    const exported = new Set();
+    EXPORTED_NAME.lastIndex = 0;
+    for (const m of source.matchAll(EXPORTED_NAME)) {
+        if (m[1])
+            exported.add(m[1]);
+        if (m[2])
+            exported.add(m[2]);
+        if (m[3]) {
+            for (const raw of m[3].split(",")) {
+                const name = raw
+                    .trim()
+                    .split(/\s+as\s+/)[0]
+                    ?.trim();
+                if (name && /^[A-Z]/.test(name))
+                    exported.add(name);
+            }
+        }
+    }
+    const out = new Set();
+    BOUND.lastIndex = 0;
+    for (const m of source.matchAll(BOUND)) {
+        const name = m[1] ?? m[2];
+        if (name && !exported.has(name))
+            out.add(name);
+    }
+    return out;
+}
 export function emptyTally() {
     return new Map();
 }
@@ -92,11 +155,16 @@ internal = []) {
     if (!/\.(tsx|jsx|vue|svelte)$/i.test(file))
         return;
     const owners = importedNames(source, internal);
+    const private_ = localOnlyNames(source);
     ELEMENT.lastIndex = 0;
     for (const m of source.matchAll(ELEMENT)) {
         if (m.index != null && looksLikeType(source, m.index))
             continue;
         const name = m[1];
+        // Private wiring, not a component of the system. An import wins: a file may
+        // shadow nothing and still bind a name it also imports.
+        if (!owners.has(name) && private_.has(name.split(".")[0]))
+            continue;
         const body = m[2] ?? "";
         let hit = tally.get(name);
         if (!hit) {

package/dist/doctor/crosswalk.js

@@ -304,8 +304,45 @@ function sharedMeaning(a, b) {
             n += 1;
     return n;
 }
-export function crosswalk(components) {
+/**
+ * WHEN THE SOURCE IS THE LIBRARY, EVERY COMPONENT IS THEIRS.
+ *
+ * The crosswalk was designed for an APP that uses components: "your Pill reads as
+ * our badge, use ours" is exactly right there, because it stops a duplicate. When the
+ * source IS the component library, the premise inverts - their library IS the design
+ * system, and mapping their component onto ours is us overwriting theirs with ours.
+ * The opposite of entering as a complement.
+ *
+ * Measured on a real library (dono, 01/08): of 37 components they export, 16 never
+ * became theirs. `Label`, `Pill` and `Tag` - three distinct components - collapsed
+ * into one `ds-badge` of ours, which is why their Tag previewed as the word "Pill":
+ * that is OUR recipe's sample text. `LineChart`, a real organism, simply was not in
+ * the system.
+ *
+ * The code already knew. `describeOrigin` says it in prose - "declared in
+ * `packages/ui` and composed nowhere inside it, which is what a component library
+ * looks like from the inside" - and then acted as if it were an app.
+ *
+ * THE SIGNAL, and it is not a guess: a library declares and does not compose itself.
+ * When most of what a scope declares is composed nowhere inside it, the scope is a
+ * library. The crosswalk still runs and its verdict still travels as INFORMATION -
+ * "this reads as our badge" is worth knowing - it just stops replacing anything.
+ */
+export function isLibrary(components) {
+    const mine = components.filter((c) => !c.from);
+    if (mine.length < 4)
+        return false;
+    const uncomposed = mine.filter((c) => (c.count ?? 0) === 0).length;
+    return uncomposed / mine.length >= 0.5;
+}
+export function crosswalk(components, 
+/**
+ * Their library is the system. Every component keeps its own recipe, and the
+ * catalogue match becomes a note rather than a substitution.
+ */
+opts) {
     const mine = components.filter((c) => !c.from);
+    const library = opts?.library ?? false;
     // Two of THEIR components reading as the same catalogue entry is the
     // strongest redundancy signal there is, and it needs no threshold: it is not
     // "these look alike", it is "you wrote this twice". The first run filed both
@@ -344,6 +381,24 @@ export function crosswalk(components) {
             .sort((a, b) => b.overlap - a.overlap);
         if (canonical && CATALOGUE[canonical]) {
             const alsoClaiming = (claims.get(canonical) ?? []).filter((n) => n !== component.name);
+            /**
+             * LIBRARY MODE: the match is a NOTE, not a verdict.
+             *
+             * Their component stays exclusive and keeps its own recipe; `canonical` still
+             * travels so a preview can resolve a frontier and so the v2 can say "these
+             * three read alike". What stops happening is their `Label` ceasing to exist.
+             */
+            if (library) {
+                return {
+                    component,
+                    canonical,
+                    twins,
+                    bucket: "exclusive",
+                    because: alsoClaiming.length > 0
+                        ? `yours, and it reads like ds-${canonical} - so do ${alsoClaiming.join(", ")}, which is one decision written ${alsoClaiming.length + 1} times`
+                        : `yours, and it reads like ds-${canonical} - kept as yours because this library IS the system`,
+                };
+            }
             if (alsoClaiming.length > 0) {
                 return {
                     component,
@@ -369,7 +424,9 @@ export function crosswalk(components) {
                 component,
                 canonical,
                 twins,
-                bucket: "nearly",
+                // A twin is a v2 observation either way; in library mode it must not cost
+                // the component its own recipe.
+                bucket: library ? "exclusive" : "nearly",
                 because: `shares ${Math.round(twins[0].overlap * 100)}% of its options with ${twins[0].name} - one decision, two components`,
             };
         }

package/dist/doctor/definitions-scan.js

@@ -20,6 +20,36 @@
  * actually write and stays silent on the rest: a props type built by `Omit<>` or
  * spread from another interface yields no axes rather than wrong ones.
  */
+/**
+ * THEIR OWN LADDER, READ OFF THE PATH - never guessed from a name.
+ *
+ * A real library keeps `atoms/Text/Text.tsx`, `molecules/MetricCard/`,
+ * `organisms/DataTable/`: the author saying out loud what composes what, in the
+ * vocabulary the whole industry already shares. Twenty-three components arrived in
+ * one flat bucket and the information was sitting in the path (dono, 01/08).
+ *
+ * A path segment, not a substring: `src/atomsphere/` is a folder called
+ * atomsphere. Returns undefined for the projects that do not organise themselves
+ * this way, which is most of them - and undefined means "no ladder here", not
+ * "unclassified".
+ */
+const TIER_FOLDER = {
+    atoms: "atom",
+    atom: "atom",
+    primitives: "atom",
+    molecules: "molecule",
+    molecule: "molecule",
+    organisms: "organism",
+    organism: "organism",
+};
+export function tierOf(file) {
+    for (const segment of file.split(/[/\\]/)) {
+        const tier = TIER_FOLDER[segment.toLowerCase()];
+        if (tier)
+            return tier;
+    }
+    return undefined;
+}
 /** `export function X`, `export default function X`, `export const X =`. */
 const EXPORTED = /export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Z][A-Za-z0-9_]*)|const\s+([A-Z][A-Za-z0-9_]*)\s*[:=])/g;
 /** `type ButtonProps = { … }` or `interface ButtonProps { … }`, to its closing
@@ -78,11 +108,13 @@ export function scanDefinitions(file, source) {
             continue;
         seen.add(name);
         const props = propsOf.get(name);
+        const tier = tierOf(file);
         out.push({
             name,
             file,
             axes: props?.axes ?? {},
             flags: props?.flags ?? [],
+            ...(tier ? { tier } : {}),
         });
     }
     return out;

package/dist/index.js

@@ -41,7 +41,7 @@ Usage - deterministic, FREE:
 
 Usage - governance (deterministic, FREE):
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
-  synthesisui import [--dry] [--scope <p>]  read the app you already have and make it a system
+  synthesisui import [--scope <p>] [--usage <p>]  read what you already have and make it a system
                                            your agent follows - without touching your CSS
   synthesisui connect                      wire your agent: the check as an editor hook, the system
                                            as MCP tools, and a contract that stops repeating itself
@@ -66,7 +66,8 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
-  --scope <path>     import: measure only this folder; the census still lands at the root
+  --scope <path>     import: the SYSTEM - tokens, components, convention. One folder.
+  --usage <path>     import: the EVIDENCE - counts, chosen values, laws. Repeatable.
   --scheme <s>       dark|light - which end of your ladder is the default
   --target <t>       template/init target: next | general (default: next)
   --pages-dir <dir>  init: folder for generated pages (default: app)
@@ -111,9 +112,30 @@ Examples:
   synthesisui generate "an upgrade banner with a title, message and a primary CTA"
 `;
 /** Extracts simple `--flag value` pairs and the remaining positionals. */
+/**
+ * A REPEATED FLAG ACCUMULATES rather than overwriting.
+ *
+ * `--usage apps/web --usage apps/admin` is the natural way to say two, and keeping
+ * only the last would drop one silently - which is the failure mode this codebase
+ * refuses everywhere else. Every existing flag is passed once and still arrives as
+ * a string, so nothing that reads `typeof flags.x === "string"` changes.
+ */
 function parseFlags(argv) {
     const positionals = [];
     const flags = {};
+    const put = (key, value) => {
+        const had = flags[key];
+        if (had === undefined) {
+            flags[key] = value;
+            return;
+        }
+        if (typeof value !== "string")
+            return;
+        flags[key] = [
+            ...(Array.isArray(had) ? had : typeof had === "string" ? [had] : []),
+            value,
+        ];
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "-h" || arg === "--help") {
@@ -124,17 +146,17 @@ function parseFlags(argv) {
             const eq = body.indexOf("=");
             if (eq !== -1) {
                 // `--key=value` form (e.g. --out=templates/page.tsx)
-                flags[body.slice(0, eq)] = body.slice(eq + 1);
+                put(body.slice(0, eq), body.slice(eq + 1));
             }
             else {
                 // `--key value` form
                 const next = argv[i + 1];
                 if (next !== undefined && !next.startsWith("--")) {
-                    flags[body] = next;
+                    put(body, next);
                     i++;
                 }
                 else {
-                    flags[body] = true;
+                    put(body, true);
                 }
             }
         }
@@ -165,6 +187,14 @@ async function main() {
                 // invert a system, so it falls through to being measured and asked.
                 // WHAT to read. `--dir` stays WHERE the project is, in every command.
                 scope: typeof flags.scope === "string" ? flags.scope : undefined,
+                // WHERE THE EVIDENCE IS. Repeatable, and comma-separated works too - a
+                // person typing one path with a comma in it means two paths.
+                usage: [flags.usage]
+                    .flat()
+                    .filter((v) => typeof v === "string")
+                    .flatMap((v) => v.split(","))
+                    .map((v) => v.trim())
+                    .filter(Boolean),
                 scheme: flags.scheme === "dark" || flags.scheme === "light"
                     ? flags.scheme
                     : undefined,

package/dist/skill-import.js

@@ -105,22 +105,42 @@ This root holds several projects
   is the average of all of them. That is a fine DIAGNOSIS and a poor system: a
   light app and a dark one average into a palette that is neither.
 
-      synthesisui import --scope packages/ui   the system comes from here
+      synthesisui import --scope packages/ui --usage apps/web-dashboard
 \`\`\`
 
-Then measure again, narrowed:
+Then measure again, narrowed - and **name both roles**:
 
 \`\`\`
-npx synthesisui import --dry --scope packages/ui
+npx synthesisui import --dry --scope packages/ui --usage apps/web-dashboard
 \`\`\`
 
+### The two roles, and why one flag could not do both
+
+\`\`\`
+--scope   the SYSTEM     tokens, components, the way they name a class    ONE folder
+--usage   the EVIDENCE   how often, which values get picked, the laws     as many as they have
+\`\`\`
+
+\`--usage\` is repeatable and never contributes a token, a scale or a component. That split is
+not tidiness, it is the two mistakes this pipeline exists to avoid, and each one has been made:
+
 **Do not import the average.** Three apps measured together produce a palette that belongs to
 none of them, and it will look plausible - a real monorepo reported 36% coverage across 2797
 files at the root and 47% across 114 in its shared package. The second number is the system;
-the first is a diagnosis.
+the first is a diagnosis. Their scale is a DECLARATION; an app's average is a set of choices
+made from one.
+
+**Do not import a library alone either.** A law needs three files that agree, and a library has
+ONE file per component - so measured by itself, a real one came back with \`usage\` empty on all
+23 components and not a single observed law. Not because nothing is settled: because the
+agreeing happens in the app (dono, 01/08). If they have apps, name them.
 
-\`--scope\` narrows what is READ. The census still lands at \`<root>/_synthesisui/census.json\`
-and records what it measured, so you always send the same path and there is never a second
+Point \`--usage\` at every app that consumes the system. A component that lives in an app and
+not in the system is reported and left out - the system is one place, and a union of two
+codebases is not a system.
+
+The census still lands at \`<root>/_synthesisui/census.json\` and records both what it measured
+and where the evidence came from, so you always send the same path and there is never a second
 file to pick between. Nothing is sent by \`--dry\`. Read the file.
 
 ### 2. Read what arithmetic cannot
@@ -398,7 +418,7 @@ shell and its own parts inside.
   \`"root": "BaseDialog.Root"\`, \`"root": "Popover.Root"\`
 - **a plain tag** - leave it out. \`<div>\`, \`<td>\`, \`<button>\` are not frontiers.
 
-### The nine forms
+### The ten forms
 
 \`as\` says what a node IS, and the renderer draws that. Nothing else is accepted:
 
@@ -413,10 +433,40 @@ row       arranges its children ACROSS
 stack     arranges its children DOWN
 component their component  → needs "ref": the name as their code spells it
 external  a library        → needs "from": the package name
+slot      the CALLER's content → takes "expects": what goes there, in their words
 \`\`\`
 
 Only \`row\` and \`stack\` take \`children\`. Everything else is a leaf.
 
+### \`{children}\` is a node, not an absence
+
+Four things decide what a component looks like on screen, and only the first is in its own source:
+
+\`\`\`
+its own classes          you are reading them
+what the caller passes   <tr>{children}</tr>          → slot
+its runtime state        value={62} drives the width  → a part with no static size
+a library drawing it     <EditorContent>              → external
+\`\`\`
+
+A component whose content is not its own had nothing to send, so it sent nothing and previewed as
+a blank box. A real \`DataTableRow\` is sixteen lines - a \`<tr>\` carrying a border, a hover and
+\`{children}\` - and it came back empty, which is not wrong so much as unreadable (dono, 01/08).
+
+So send the slot. \`expects\` is what the caller is supposed to put there, in the words their own
+code uses - read the prop type, the JSDoc, or a call site:
+
+\`\`\`json
+{ "as": "slot", "name": "row", "classes": "border-b hover:bg-ocean-50/30", "expects": "the cells" }
+\`\`\`
+
+It keeps its \`name\` and \`classes\` like any other node - the border and the hover are real and
+belong on that element. What it does not do is invent content: the preview says "the cells go
+here", which is exactly what the file says.
+
+Good \`expects\`: \`"the cells"\`, \`"one row per item"\`, \`"the form"\`, \`"the page body"\`. Leave it
+out rather than writing \`"children"\` - the field is for what a person would call it.
+
 **\`name\` is the part name**, and it is what carries the styles - flat, lowercase, kebab. Never
 nested: \`"actions.generate"\` compiles to two CSS classes and is invalid, so name it
 \`"generate-action"\`. Name what it IS - \`label\`, \`value\`, \`delta\`, \`cover\`, \`toolbar\` - because the
@@ -440,10 +490,22 @@ of. It previews as a block carrying its name, and it becomes a **rule** - \`Arti
 That edge is a **fact, not a habit**: you saw it in the definition, so it is true once and for
 all, and it arrives active without waiting for a third sighting.
 
-Two things that are NOT edges, and sending them as such would be wrong:
+Three things that are NOT edges, and sending them as such would be wrong:
 
 - \`motion.div\`, \`Dialog.Root\`, \`Radio.Item\` - a library's namespace, not a component of theirs
 - an HTML element with a capital in a variable name
+- **a name the file binds itself and does not export.** Capitalisation is React's rule for "not an
+  html tag", which is a different question from "is this a component of the system". Both of these
+  arrived as components of a real library and neither is one (dono, 01/08):
+
+\`\`\`tsx
+function Text({ as: Component = "p" })   // a prop rename - the polymorphic idiom
+const CustomLegend = () => (…)           // a closure inside LineChart
+\`\`\`
+
+  The test is reachability: a component of the system is imported from somewhere or exported to
+  somewhere. A name that only lives inside one function body is that function's private wiring,
+  and giving it a recipe invents a component nobody can import.
 
 If the component came from a package, it is \`external\`, not \`component\`.
 
@@ -497,7 +559,7 @@ spec view has no nesting to draw.
 
 ### 3. Walk them through the decisions, one at a time
 
-Four decisions are theirs. **Ask them as separate questions with selectable options** - use your
+Five decisions are theirs. **Ask them as separate questions with selectable options** - use your
 question tool, one call per decision, so they pick instead of reading a wall and composing a
 reply. A single block containing everything is a report, and a report gets read, not answered.
 
@@ -581,6 +643,36 @@ canvas  #222326  darkgray-500 - what DashboardLayout paints on <main>
 Say it and let them object. Offering five near-blacks to pick between is asking someone to
 re-decide something their code already decided.
 
+**3e-bis. Our kit, or theirs alone** - ask this ONLY when they already have a component library,
+which is when \`--scope\` pointed at one and the CLI said so. An app with no components of its own
+has nothing to weigh and should never see the question.
+
+\`\`\`
+Every system born here comes with 45 components of ours - button, card, input,
+table, the rest of a working toolkit. You already have 37.
+
+  add ours to yours (recommended)   68 components, and the 23 governed by your
+                                    own rules are the 23 you wrote
+  mine alone                        37 components, all of them yours. Our
+                                    layouts that need a component you do not
+                                    have stay out too. Add any of ours later
+                                    from the library, one at a time
+\`\`\`
+
+Send it as \`"standards": "none"\` in the reading when they choose the second, and leave the field
+out when they choose the first. **Recommend adding ours**, and say why in one line: a component of
+ours costs nothing until something composes it, and having a \`table\` the day somebody needs a
+table is worth more than a shorter list.
+
+Two things to be straight about, because both are true and neither is obvious:
+
+- **the foundations come from the seed either way.** Their palette, their scales, their type - all
+  theirs - but the seven type slots, the easing and the neutral floor arrive from ours, because
+  the alternative to a type scale is no components at all rather than their components.
+- **our layouts are written in our recipes.** A landing that composes \`button\`, \`card\` and
+  \`badge\` needs those to exist. Choosing *mine alone* keeps the layouts whose recipes they
+  happen to have and drops the rest - a layout pointing at a recipe nobody has renders as holes.
+
 **3f. Fonts** - do not ask at all. Report and move on:
 
 \`\`\`
@@ -595,7 +687,7 @@ way. If it declares one, there is nothing to decide.
 carries the weight - \`ocean-500\` tells someone more than a square would. When they run
 \`npx synthesisui import\` themselves in a terminal, the CLI paints them.
 
-Then, and only after all four are answered:
+Then, and only after all of them are answered:
 
 \`\`\`
 npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--registry <from step 0>]
@@ -603,7 +695,7 @@ npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--
 
 **This is the one real write.** Everything before it is on their disk and costs nothing to redo.
 
-Pass every answer explicitly - \`--name\`, \`--scope\` if they changed it, and the reading rewritten
+Pass every answer explicitly - \`--name\`, \`--scope\` and \`--usage\` if they changed either, and the reading rewritten
 with their primary and their theme. The CLI cannot ask anything when you are the one running it:
 it has no terminal, so its own prompts are skipped by design. **Whatever you did not ask, nobody
 asked.** Skip 3a and the first time they learn where their system came from is when they open
@@ -627,6 +719,10 @@ proposal. Say all of this in your own words - do not just print the link:
   which half was deliberate: nothing was invented, so a component whose classes named no token
   arrives with structure and no colour. The platform shows that as *Not written yet*, not as a
   zero.
+- **their own ladder**, if their repo has one. Components under \`atoms/\`, \`molecules/\` and
+  \`organisms/\` arrive grouped that way in the vitrine, read off the folder rather than guessed
+  from a name. You do not send this and you should not try to: a project that does not organise
+  itself this way gets one honest group instead of three invented ones.
 - **the shape of each component**, if you sent one: its parts nested as they nest in their code,
   the components of theirs it composes, and the libraries it needs. Each edge is also a rule now,
   which is what makes it survive being looked at once.

package/package.json

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