synthesisui 0.16.78 → 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"]);
@@ -95,7 +96,11 @@ function formOf(node) {
  * `declared` is their own tokens, so a `bg-ocean-500` on a nested part resolves
  * to the name they gave it rather than to a literal.
  */
-export function resolveAnatomy(read, declared, deps) {
+export function resolveAnatomy(read, declared, deps, 
+/** Their name → the slug it reaches in this system. See `RefResolver`. */
+resolve, 
+/** What the component returns, when the skill said and it is not a plain tag. */
+root) {
     const parts = {};
     const composes = [];
     const external = [];
@@ -147,12 +152,22 @@ export function resolveAnatomy(read, declared, deps) {
             // on one would be us claiming styles that belong to somebody else.
             if (FRONTIERS.has(as)) {
                 if (as === "component") {
-                    const ref = String(node.ref ?? "").trim();
-                    if (!ref)
+                    const name = String(node.ref ?? "").trim();
+                    if (!name)
                         continue;
-                    if (!composes.includes(ref))
-                        composes.push(ref);
-                    out.push({ as, ref });
+                    if (!composes.includes(name))
+                        composes.push(name);
+                    /**
+                     * THE CROSSWALK DECIDES WHAT THIS REACHES.
+                     *
+                     * `Tag` is bucketed `nearly` with canonical `badge`; kebab-casing it
+                     * looks for `ds-tag` and finds nothing. Without a resolver we keep the
+                     * kebab, which is what a system generated by us would want anyway.
+                     */
+                    const slug = resolve?.(name) ?? safePartName(name);
+                    out.push(slug && slug !== safePartName(name)
+                        ? { as, ref: slug, refName: name }
+                        : { as, ref: slug || safePartName(name) });
                     continue;
                 }
                 const from = String(node.from ?? "").trim();
@@ -184,6 +199,19 @@ export function resolveAnatomy(read, declared, deps) {
             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)) {
@@ -202,13 +230,40 @@ export function resolveAnatomy(read, declared, deps) {
         return out;
     };
     const tree = walk(top, 0);
+    /**
+     * THE ROOT, RESOLVED THE SAME WAY.
+     *
+     * A dotted capitalised name is somebody else's namespace - `Radio.Root`,
+     * `BaseDialog.Root` - so there is nothing of theirs to reach and the honest
+     * answer is to name the library. Anything else is a component of theirs and goes
+     * through the crosswalk exactly like a child frontier does.
+     */
+    let rootOut;
+    const rootRaw = String(root ?? "").trim();
+    if (rootRaw && /^[A-Z]/.test(rootRaw)) {
+        if (rootRaw.includes(".")) {
+            rootOut = { from: rootRaw };
+        }
+        else {
+            const slug = resolve?.(rootRaw) ?? safePartName(rootRaw);
+            if (slug)
+                rootOut = { ref: slug, name: rootRaw };
+        }
+    }
     if (coerced > 0) {
         notes.push(`${coerced} node${coerced === 1 ? "" : "s"} named a form that does not exist - kept, drawn as what ${coerced === 1 ? "it holds" : "they hold"}`);
     }
     if (budget <= 0) {
         notes.push(`the anatomy was longer than ${MAX_NODES} nodes - the rest is layout, and it is not read`);
     }
-    return { parts, tree, composes, external, notes };
+    return {
+        parts,
+        tree,
+        composes,
+        external,
+        notes,
+        ...(rootOut ? { root: rootOut } : {}),
+    };
 }
 /**
  * The OLD flat form, folded into the same result shape.

package/dist/commands/component.js

@@ -5,7 +5,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
-import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
+import { findCollision, reactMajorOf, readInstalledConvention, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -68,6 +68,43 @@ export async function component(slug, name, opts) {
     const config = await readProjectConfig(root);
     const wantInteractive = opts.interactive && hasInteractiveTemplate(res.name);
     if (!opts.artifactsOnly && config.target === "next") {
+        /**
+         * WE DO NOT TAKE A NAME THEY ARE USING.
+         *
+         * This wrote with a bare `writeFile`, so it overwrote whatever was there - and
+         * a project that already has its own `Button` is the normal case. The
+         * crosswalk makes it sharper: their `ToolbarButton` resolves to `button`, so
+         * asking for one hands back a `Button`, which is a different component.
+         *
+         * Re-materializing something WE generated is almost always what they meant, so
+         * that keeps going. Shadowing a component of theirs stops and asks.
+         */
+        const pascalName = res.name
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        const clash = await findCollision(root, config.componentsDir, res.name, pascalName);
+        if (!opts.force && (clash.exported || (clash.file && !clash.ours))) {
+            console.log(section("This name is already taken in your project"));
+            if (clash.exported) {
+                console.log(body(`\`${pascalName}\` is already exported from ${clash.exported}.`));
+            }
+            if (clash.file && !clash.ours) {
+                console.log(body(`${clash.file} exists and we did not write it.`));
+            }
+            console.log("");
+            console.log(body("The recipe and the compiled CSS are on disk either way - only the .tsx was not written. Your options:"));
+            console.log("");
+            console.log(snippet([
+                `npx synthesisui component ${slug} ${res.name} --force`,
+                `# or bring it under a name of your own:`,
+                `npx synthesisui component ${slug} ${res.name} --as my-${res.name}`,
+            ]));
+            console.log("");
+            console.log(body("Nothing of yours was touched. Which name it takes is your call, not ours."));
+            return;
+        }
         const compDir = join(root, config.componentsDir, res.name);
         await mkdir(compDir, { recursive: true });
         let filenames;

package/dist/commands/import.js

@@ -1,12 +1,12 @@
-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, } from "../anatomy-read.js";
+import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 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 merged = [...enriched, ...fromTypes];
+    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 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:"));
@@ -924,10 +1070,28 @@ async function resolveReadParts(census, root) {
     let edges = 0;
     const libs = new Set();
     const notes = new Set();
+    /**
+     * WHAT A NAME IN THEIR CODE REACHES IN THE SYSTEM - from the crosswalk.
+     *
+     * The census already decided this for every component it read: `Tag` is
+     * `nearly`, canonical `badge`; `ToolbarButton` is `nearly`, canonical `button`;
+     * `Card` `exists` as `card`. The first version of the frontier kebab-cased the
+     * name and looked for `ds-tag`, which does not exist - so a component whose
+     * recipe was sitting right there drew as a grey chip (dono, 01/08).
+     */
+    const crosswalked = new Map();
+    for (const c of census.components ?? []) {
+        if (c.from)
+            continue; // a package's component is not one of theirs
+        const target = c.canonical ?? (c.bucket === "exclusive" ? c.name : null);
+        if (target)
+            crosswalked.set(c.name, safePartName(target));
+    }
+    const resolveRef = (name) => crosswalked.get(name) ?? null;
     for (const [component, entry] of Object.entries(read)) {
         const anatomy = entry?.anatomy;
         const resolved = Array.isArray(anatomy) && anatomy.length > 0
-            ? resolveAnatomy(anatomy, declared, deps)
+            ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root)
             : Array.isArray(entry?.parts) && entry.parts.length > 0
                 ? resolveFlatParts(entry.parts, declared)
                 : null;
@@ -942,6 +1106,7 @@ async function resolveReadParts(census, root) {
             ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
             ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
             ...(resolved.external.length > 0 ? { external: resolved.external } : {}),
+            ...(resolved.root ? { root: resolved.root } : {}),
         };
         looks[component] = look
             ? {
@@ -998,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;
@@ -1041,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

@@ -65,6 +65,20 @@ const TOOLS = [
         description: "The components this design system defines, with what each is for. Look here BEFORE writing any UI element from scratch - if something covers the purpose, materialize it with add_component instead.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "describe_component",
+        description: "Everything the system knows about ONE component: what it is made of, what it composes, WHICH LIBRARIES IT NEEDS, and the rules that govern it. Call this before writing code that uses a component - `list_components` gives you a name and a sentence, and a name does not tell you that the editor needs @tiptap/react or that a card is built out of a metric card.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Component name from list_components.",
+                },
+            },
+            required: ["name"],
+        },
+    },
     {
         name: "add_component",
         description: "Materialize a component from the design system as real typed code in this project, ready to import and extend. Use it yourself - the person who asked for a feature should never have to know component names.",
@@ -191,6 +205,118 @@ async function listComponents(root) {
         ...rows.sort(),
     ].join("\n");
 }
+/**
+ * ONE COMPONENT, IN FULL - the round trip that did not exist.
+ *
+ * `list_components` returns a name and a description, so an agent building with
+ * `ds-text-editor` had no way to know it needs `@tiptap/react` before writing the
+ * first line. The anatomy, the composition chain and the required libraries are all
+ * in the installed contract; nothing was asking for them.
+ *
+ * It is also the confirmation the skill never had. After an import, reading this
+ * back says what the platform UNDERSTOOD - so a reading that came out thin is
+ * visible instead of being discovered later in a preview.
+ */
+async function describeComponent(root, name) {
+    const { documents, requires } = await loadSystem(root);
+    let recipe;
+    for (const doc of documents) {
+        const d = doc;
+        recipe = d.components?.[name] ?? d.blocks?.[name];
+        if (recipe)
+            break;
+    }
+    if (!recipe) {
+        return `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`;
+    }
+    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;
+    if (p?.rootRef) {
+        out.push("", `Sits on: ${p.rootRef}${p.rootName && p.rootName !== p.rootRef ? ` (your ${p.rootName})` : ""} - its background, border and radius come from there, not from this component.`);
+    }
+    else if (p?.rootFrom) {
+        out.push("", `Sits on: ${p.rootFrom} - a third-party root. Its markup and behaviour are that library's.`);
+    }
+    // WHAT IT IS MADE OF, and where it ends.
+    const composes = [];
+    const libs = [];
+    const shape = [];
+    const walk = (nodes, depth) => {
+        for (const raw of nodes) {
+            const n = raw;
+            const pad = "  ".repeat(depth + 1);
+            if (n.as === "component" && n.ref) {
+                shape.push(`${pad}<${n.ref}>${n.refName && n.refName !== n.ref ? `  (your ${n.refName})` : ""}`);
+                if (!composes.includes(n.ref))
+                    composes.push(n.ref);
+            }
+            else if (n.as === "external" && n.from) {
+                shape.push(`${pad}${n.from}  (third party - not ours to render)`);
+                if (!libs.includes(n.from))
+                    libs.push(n.from);
+            }
+            else {
+                shape.push(`${pad}${n.as}${n.part ? ` .${name}-${n.part}` : ""}`);
+            }
+            if (Array.isArray(n.children))
+                walk(n.children, depth + 1);
+        }
+    };
+    if (Array.isArray(p?.parts) && p.parts.length > 0) {
+        walk(p.parts, 0);
+        out.push("", "Made of:", ...shape);
+    }
+    else if (recipe.parts && Object.keys(recipe.parts).length > 0) {
+        out.push("", `Parts: ${Object.keys(recipe.parts).join(", ")} - compose them inside it.`);
+    }
+    if (composes.length > 0) {
+        out.push("", `Built out of: ${composes.join(", ")}. Change one of those in one place rather than reproducing it here, and call describe_component on it before you do.`);
+    }
+    /**
+     * WHAT IT NEEDS INSTALLED - the whole reason this tool earns its place.
+     *
+     * From `requires.json`, filtered by the stack at install time, so the answer is
+     * about THIS project. Never installs: a dependency has a licence, a bundle cost
+     * and a maintainer attached, so the agent reports and the person decides.
+     */
+    const needed = requires.filter((r) => (r.applies ?? []).includes(name));
+    if (needed.length > 0 || libs.length > 0) {
+        const named = [
+            ...new Set([...needed.map((r) => r.requires), ...libs]),
+        ];
+        out.push("", `Needs installed: ${named.join(", ")}.`, "Check the manifest before you write against it. If it is missing, say so and ASK - do not install it yourself.");
+        for (const r of needed) {
+            if (r.pinned)
+                out.push(`  ${r.requires}  ${r.pinned}`);
+        }
+    }
+    // THE RULES, scoped. A relation names both, which is what an agent needs in
+    // order not to assemble it wrongly.
+    const laws = [...(recipe.usage ?? [])];
+    if (laws.length > 0) {
+        out.push("", "Rules for this component:", ...laws.map((l) => `  ${l}`));
+    }
+    if (needed.length > 0) {
+        out.push(...needed.map((r) => `  ${r.text}`));
+    }
+    if (laws.length === 0 && needed.length === 0) {
+        out.push("", "No rules govern this component yet. Build with it, and if you find yourself working around it, file request_component with the reasoning.");
+    }
+    return out.join("\n");
+}
 async function addComponent(root, name) {
     const { table } = await loadSystem(root);
     if (!table.slug)
@@ -207,6 +333,8 @@ async function callTool(root, name, args) {
             return text(await findToken(root, String(args.value ?? "")));
         case "list_components":
             return text(await listComponents(root));
+        case "describe_component":
+            return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
             return text(await addComponent(root, String(args.name ?? "")));
         case "request_component": {