synthesisui 0.16.93 → 0.16.95

package/dist/commands/import.js

@@ -23,7 +23,7 @@ import { buildTable } from "../doctor/tokens.js";
 import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
 import { body, paint, section } from "../output.js";
-import { startProgress } from "../progress.js";
+import { phase, startProgress } from "../progress.js";
 import { detectStack, resolveDeps } from "../stack.js";
 import { walk, walkAll } from "./doctor.js";
 /**
@@ -396,7 +396,30 @@ export async function takeCensus(root, opts) {
             // component's own look, and everything below it is a part this slice does
             // not attempt.
             if (found.length > 0) {
-                const t = transcribe(rootClasses(src), declaredValues);
+                /**
+                 * EVERY COMPONENT THE FILE DEFINES, not just the first.
+                 *
+                 * One file in a real library defines two - `RadioCard` and
+                 * `RadioCardGroup` - and the second arrived with an empty base while its
+                 * `flex flex-col gap-3` sat six lines below the first component's return
+                 * (audit, dono, 01/08). The file-level readings (the CSS module, the
+                 * variant tables) belong to the PRIMARY definition; the root classes and
+                 * the root tag are per component, scoped by name.
+                 */
+                for (const extra of found.slice(1)) {
+                    const et = transcribe(rootClasses(src, extra.name), declaredValues);
+                    const etag = rootTag(src, extra.name);
+                    const esize = Object.keys(et.base).length +
+                        Object.keys(et.dark).length +
+                        Object.keys(et.states).length;
+                    if (esize > 0 || etag) {
+                        looks[extra.name] = {
+                            ...et,
+                            ...(etag ? { rootTag: etag } : {}),
+                        };
+                    }
+                }
+                const t = transcribe(rootClasses(src, found[0].name), declaredValues);
                 /**
                  * THE VARIANT STYLES, FOLDED IN.
                  *
@@ -480,7 +503,7 @@ export async function takeCensus(root, opts) {
                     Object.keys(states).length +
                     Object.keys(parts).length +
                     layers.length;
-                const tag = rootTag(src);
+                const tag = rootTag(src, found[0].name);
                 /**
                  * THE SKETCH travels with the look, so the reading phase never opens this
                  * file again: naming parts is a sentence over data the census already holds,
@@ -1774,9 +1797,17 @@ export async function runImport(opts) {
          * Resolved here rather than at measure time because the reading arrives
          * AFTER the census was taken - this is the first moment both halves exist.
          */
+        phase(2, 3, "Resolving the reading against the census");
         await resolveReadParts(census, root);
     }
     else {
+        /**
+         * THE MACRO STEP. Three lines for a run, not thirty: a person watching wants
+         * to know which phase they are in and how far into it, and everything else -
+         * every file opened, every candidate ruled out - is the machine talking to
+         * itself (dono, 01/08).
+         */
+        phase(1, 3, "Measuring the repository");
         console.log(section("Reading your project"));
         census = await takeCensus(readFrom, {
             ...(usage.length > 0 ? { usage } : {}),
@@ -1859,6 +1890,7 @@ export async function runImport(opts) {
         console.log("");
         return;
     }
+    phase(3, 3, "Sending v1 and the v2 proposal");
     const res = await fetch(`${base}/api/onboarding/import`, {
         method: "POST",
         headers: {

package/dist/commands/mcp.js

@@ -117,6 +117,28 @@ const TOOLS = [
             required: ["recipe"],
         },
     },
+    {
+        name: "validate_recipes",
+        description: "The SAME question as validate_recipe, asked once for a whole reading. Send every recipe you are about to write and get one report back: which would arrive whole, and for the rest what would not survive, by name. Validating 35 components one at a time is 35 round trips and none of them thinking - this is one. Prefer it whenever you have more than one recipe in hand.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                recipes: {
+                    type: "array",
+                    description: "Every candidate, in the document's own shape: [{ name, recipe }].",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            recipe: { type: "object" },
+                        },
+                        required: ["recipe"],
+                    },
+                },
+            },
+            required: ["recipes"],
+        },
+    },
     {
         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.",
@@ -333,6 +355,63 @@ async function validateRecipe(name, recipe) {
     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");
 }
+/**
+ * A WHOLE READING, VALIDATED IN ONE QUESTION.
+ *
+ * `validate_recipe` is right and it is one round trip per component: a reader
+ * with 35 anatomies in hand spent 35 turns asking the same question, and that
+ * was the largest single block of wall-clock in a real import with none of it
+ * thinking (dono, 01/08). Every answer is independent, so batching costs nothing
+ * in fidelity - the server runs the same judgment per recipe.
+ *
+ * The report leads with the count that decides what to do next, then names only
+ * what would NOT survive. A list of 30 "this one is fine" lines is a wall the
+ * reader has to skim to find the two that matter.
+ */
+async function validateRecipes(entries) {
+    if (entries.length === 0)
+        return "Send at least one recipe: { recipes: [{ name, recipe }] }.";
+    const answer = await askCatalogue("validate", { recipes: entries });
+    if (!answer.ok)
+        return answer.because;
+    const body = answer.body;
+    /**
+     * A SERVER THAT DOES NOT KNOW THE BATCH still has to answer usefully - a
+     * published CLI meeting an older host must degrade to the singular rather than
+     * print a shape error. One round trip per recipe is slower and it is correct.
+     */
+    if (!body.batch || !Array.isArray(body.results)) {
+        const one = [];
+        for (const e of entries)
+            one.push(await validateRecipe(String(e.name ?? "this component"), e.recipe));
+        return `This host does not answer batches, so each was asked on its own.\n\n${one.join("\n\n")}`;
+    }
+    const results = body.results;
+    const bad = results.filter((r) => r.ok !== true);
+    const lines = [
+        `${results.length} recipes validated - ${results.length - bad.length} would arrive whole.`,
+    ];
+    if (bad.length === 0) {
+        lines.push("", "Nothing to fix. Send them.");
+        return lines.join("\n");
+    }
+    lines.push("", `${bad.length} would NOT arrive whole:`);
+    for (const r of bad) {
+        lines.push("", `## ${r.name ?? "this component"}`);
+        for (const x of r.rejected ?? [])
+            lines.push(`  REFUSED ${x.at}: ${x.why}`);
+        for (const l of r.lost ?? [])
+            lines.push(`  DROPPED BY THE COMPILER  ${l}`);
+        for (const m of r.missing ?? [])
+            lines.push(`  BELOW THE FLOOR  ${m}`);
+        if (r.deferred)
+            lines.push(`  floor deferred: ${r.deferred}`);
+        for (const c of r.checklist ?? [])
+            lines.push(`  - go look for: ${c}`);
+    }
+    lines.push("", "Write these 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.
  *
@@ -585,6 +664,10 @@ async function callTool(root, name, args) {
             return text(await recipeVocabulary());
         case "validate_recipe":
             return text(await validateRecipe(String(args.name ?? "this component"), args.recipe));
+        case "validate_recipes":
+            return text(await validateRecipes(Array.isArray(args.recipes)
+                ? args.recipes
+                : []));
         case "request_component": {
             const r = await fileRequest(root, {
                 kind: "component",

package/dist/doctor/sketch.js

@@ -19,10 +19,75 @@
  * same in an atomic library, a feature-foldered app, or a single flat directory.
  */
 import { scanTags } from "./css-modules.js";
-/** Past this a component is a page in disguise, and the gate already said no. */
-const MAX_NODES = 60;
+/**
+ * Past this a component is a page in disguise, and the gate already said no.
+ *
+ * 60 was a guess and it cost a real read: measured across the owner's library,
+ * exactly ONE component overflows it - `TextEditor`, 67 nodes - and the seven it
+ * lost included `EditorContent`, the editable region that is the whole point of
+ * the component. So the skill opened TextEditor.tsx by hand at line 353, which
+ * is the "a file read whose content the census already carries is a pipeline
+ * optimization failure" rule breaking on our own cap (not-expressed.md, dono,
+ * 01/08).
+ *
+ * At 150 nothing in that library truncates (largest after TextEditor: 43), and
+ * 200 buys nothing over 150 - so 150 is the measured ceiling, not a rounder
+ * guess. The gate upstream is what keeps a page out; this only keeps a big
+ * COMPONENT whole.
+ */
+const MAX_NODES = 150;
 /** `className="..."` or className={"..."} / {`...`} with no interpolation. */
 const CLASS_ATTR = /className=\{?["'`]([^"'`{}$]*)["'`]\}?/;
+/**
+ * `className={cn("a b", "c", cond && "d", record[x])}` - the STATIC strings.
+ *
+ * The plain-attr regex above sees a call expression and reads nothing, and
+ * 19 of 36 components in a real library style exactly this way - so their
+ * elements arrived in the sketch with no classes at all, and the Tooltip's
+ * popup carried none when the base had to be transcribed by hand
+ * (not-expressed.md, dono, 01/08). The always-on string arguments ARE the
+ * element's resting classes; the conditional halves are variants, which the
+ * variant readers already read - so only TOP-LEVEL string literals count.
+ * Template literals with `${}` and computed values stay out: a class we
+ * cannot see in full is a class we would be guessing at.
+ *
+ * THE NAMESPACE COUNTS. Measured on the real library: 64 calls are a bare
+ * `cn(`, 11 are `twUtils.cn(` and 2 are `clsx(` - and the first version of this
+ * regex read only the bare form, so a Modal's whole surface (its fill, border,
+ * radius and padding) stayed invisible while its siblings read fine
+ * (e2e, dono, 01/08).
+ */
+const CLASS_CALL = /className=\{\s*(?:[A-Za-z_$][\w$]*\.)?(?:cn|clsx|classNames|cx|twMerge|twJoin|classcat)\(/;
+function staticCallClasses(body) {
+    const call = CLASS_CALL.exec(body);
+    if (!call)
+        return null;
+    const start = call.index + call[0].length;
+    // Walk the call's arguments at depth 0, collecting bare string literals.
+    let depth = 1;
+    let argStart = start;
+    const args = [];
+    for (let i = start; i < body.length && depth > 0; i++) {
+        const ch = body[i];
+        if (ch === "(" || ch === "{" || ch === "[")
+            depth += 1;
+        else if (ch === ")" || ch === "}" || ch === "]") {
+            depth -= 1;
+            if (depth === 0)
+                args.push(body.slice(argStart, i));
+        }
+        else if (ch === "," && depth === 1) {
+            args.push(body.slice(argStart, i));
+            argStart = i + 1;
+        }
+    }
+    const classes = args
+        .map((a) => a.trim())
+        .filter((a) => /^(["'`]).*\1$/.test(a) && !a.includes("${"))
+        .map((a) => a.slice(1, -1).trim())
+        .filter(Boolean);
+    return classes.length > 0 ? classes.join(" ") : null;
+}
 /**
  * The sketch of one component file.
  *
@@ -47,6 +112,11 @@ export function sketchOf(source) {
         const cls = CLASS_ATTR.exec(event.body);
         if (cls?.[1].trim())
             node.classes = cls[1].trim();
+        else {
+            const called = staticCallClasses(event.body);
+            if (called)
+                node.classes = called;
+        }
         // Literal text: the slice between this open and the next event, when it is prose.
         const next = events[i + 1];
         if (next) {

package/dist/doctor/transcribe.js

@@ -1090,15 +1090,40 @@ export function transcribe(classes, declared) {
  * which is still a signal, just a weaker one, so it travels as written and the
  * platform decides what to do with it.
  */
-export function rootTag(source) {
-    const ret = source.search(/return\s*\(/);
+/**
+ * WHERE *THIS* COMPONENT'S `return (` IS.
+ *
+ * Both readers below took the FIRST `return (` in the file, which is right for
+ * the 34 files that define one component and wrong for the one that defines
+ * two: `RadioCard.tsx` exports `RadioCard` and `RadioCardGroup`, and the group
+ * - a real `flex flex-col gap-3` - arrived with an empty base and the screen
+ * said "Not written yet" over it (audit, dono, 01/08).
+ *
+ * Scoped by NAME when a name is given: find that declaration, then its return.
+ * Absent or unfound, the old behaviour stands exactly - which keeps every
+ * single-component file reading byte-identically.
+ */
+function returnAt(source, name) {
+    if (name) {
+        const decl = new RegExp(`(?:function|const|let|var)\\s+${name}\\b|${name}\\s*[:=]\\s*(?:function|\\()`).exec(source);
+        if (decl) {
+            const from = source.slice(decl.index);
+            const ret = from.search(/return\s*\(/);
+            if (ret !== -1)
+                return decl.index + ret;
+        }
+    }
+    return source.search(/return\s*\(/);
+}
+export function rootTag(source, name) {
+    const ret = returnAt(source, name);
     if (ret === -1)
         return null;
     const m = /<([A-Za-z][A-Za-z0-9.]*)/.exec(source.slice(ret));
     return m ? m[1] : null;
 }
-export function rootClasses(source) {
-    const ret = source.search(/return\s*\(/);
+export function rootClasses(source, name) {
+    const ret = returnAt(source, name);
     if (ret === -1)
         return [];
     const open = source.indexOf("<", ret);

package/dist/progress.js

@@ -17,6 +17,22 @@ const BAR_WIDTH = 24;
 /** Every this-many items, the non-TTY path prints one line. Enough to see movement in
  *  a piped log without turning it into the log. */
 const MILESTONE_EVERY = 25;
+/**
+ * THE MACRO STEP - "2/3 Validating recipes", on its own line, once.
+ *
+ * A run that prints every grep it ran spends the person's attention on
+ * mechanics, and one that prints nothing for minutes is indistinguishable from
+ * one that hung (dono, 01/08). Three lines for three phases is the whole
+ * contract: the bar underneath says how far into THIS phase it is, and nothing
+ * else gets a line.
+ *
+ * Written to stderr on purpose. A phase banner is progress, not output: a caller
+ * piping stdout to a file - or the skill reading a census off it - gets the data
+ * clean, and a person at the terminal still sees both.
+ */
+export function phase(n, of, title, write = (s) => process.stderr.write(s)) {
+    write(`\n${n}/${of} ${title}\n`);
+}
 /** A bar that reads as a bar at any width. Two glyphs, no colour: this line is
  *  overwritten dozens of times a second and anything fancier flickers. */
 function bar(done, total) {

package/dist/skill-import.js

@@ -64,7 +64,9 @@ cannot expire on a host that never issued it. That is how a full read ended in a
 twice (dono, 31/07).
 
 So if the file says \`"registry": "http://localhost:3000"\`, every command in this skill carries
-\`--registry http://localhost:3000\`. If it says production, pass nothing. The CLI now refuses a
+\`--registry http://localhost:3000\`. If it says production, pass nothing. **Read that file ONCE**
+and carry the answer for the whole run - re-reading it before each command is a round trip that
+answers a question already answered. The CLI now refuses a
 mismatch instead of letting the server reject it, but the point is not to reach that.
 
 **Do this silently.** Which host you are pointed at and which flags follow from it is plumbing,
@@ -143,7 +145,196 @@ The census still lands at \`<root>/_synthesisui/census.json\` and records both w
 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
+### 2. Walk them through the decisions - ALL of them, before any reading
+
+**Every question this skill asks is answerable from the census you just took.** Source, name,
+primary, theme, canvas, our-kit-or-theirs, architecture - the numbers behind all seven are in
+the file on their disk, and none of them needs the anatomy.
+
+They used to be asked AFTER the reading, and that put six hundred lines of work between the
+person's first answer and their second (dono, 01/08). A person who answers seven questions in
+ninety seconds and then watches a bar has had a good four minutes; the same person interrupted
+twice in the middle of a silence has had a bad twenty.
+
+So: ask everything here, in one pass, and **do not come back**. If something you learn during
+the reading contradicts an answer, you do not reopen the question - you say so in the report at
+the end and let them change it there.
+
+Seven 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.
+
+Every question carries **your recommendation first, marked as such**, and the evidence for it in
+one line. They are choosing, not auditing you.
+
+**2a. Source** - the folder you measure the system out of.
+
+Options are the candidates the CLI already ranked, each with what it would produce, plus the
+whole repo, plus *somewhere else* for a path they type:
+
+\`\`\`
+Where should the system come from?
+
+  packages/ui (recommended)    114 files · 47% of its values already named ·
+                               92 tokens of their own · every app imports it
+  the whole repo               2797 files · 36% · the average of one dark app
+                               and two light ones, which is a diagnosis and
+                               not a system
+  apps/web-dashboard           the heaviest consumer, if you want one app's
+                               vocabulary rather than the shared one
+  somewhere else               a path you name
+\`\`\`
+
+If they name a path you cannot use, say which of the two it is and offer the list again:
+
+- **it does not exist**, or holds no files you can read
+- **it holds no design values** - no colours, no radii, no tokens. A folder of server code or
+  config is not a design system, and measuring it produces a system of nothing.
+
+**2b. Name** - suggest theirs, and let Enter take it:
+
+\`\`\`
+What should it be called?  (SignalUI)
+\`\`\`
+
+Say where the suggestion came from - \`Introduction.mdx\`, the package name, the folder. A name
+they recognise is worth more than a clever one. The slug is derived once and never changes, so
+this is the moment.
+
+**2c. Primary** - and explain the role before offering the choice, because *primary* is our word
+and not necessarily theirs:
+
+\`\`\`
+Primary is the colour that carries action - buttons, links, focus, the thing
+you want pressed. Everything else in the system is measured for contrast
+against it.
+
+  #059aed  ocean-500 (recommended)     your ColorPalette.mdx calls Ocean the
+                                       "Primary branding scale"
+  #1a4ed8  royal-blue-500              your docs label this one secondary
+  #ec4899  vivid-pink-500              half of your signature AI gradient
+  #4A90E2  blue-500                    the most-painted blue in the folder,
+                                       but it sits after your own
+                                       /* End - Signal UI */ marker
+\`\`\`
+
+Always name the hex AND the token, and always give the reason a value is *not* recommended when
+frequency would have picked it. That last row is the whole point of asking.
+
+**2d. Default theme** - which face it opens in:
+
+\`\`\`
+  dark (recommended)   data-theme="dark" in the root layout, next-themes
+                       defaultTheme="dark", enableSystem={false}
+  light                the other one, also real here
+\`\`\`
+
+**Two is all there is** - a SynthesisUI system carries one palette and one alternate, and the
+schema is \`"light" | "dark"\`. So this is not "which themes do you support", it is "which one do
+docs and installs open in". If both are real, both get built from their own tokens; this picks
+the face.
+
+**2e. Canvas** - confirm, do not offer a list. The page is measured, not chosen:
+
+\`\`\`
+canvas  #222326  darkgray-500 - what DashboardLayout paints on <main>
+                 (your sidebar sits a step deeper at darkgray-700)
+\`\`\`
+
+Say it and let them object. Offering five near-blacks to pick between is asking someone to
+re-decide something their code already decided.
+
+**2f. 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.
+
+**2g. Which architecture has priority** - ask only when the CLI reported more than
+one, which it does under "How this project is organised".
+
+A project having two shapes is not a project with a mistake: a library organised
+atomically inside a monorepo whose apps are organised by feature is two true answers.
+Say that before you ask, or the question reads as an accusation.
+
+\`\`\`
+Two shapes, and neither is wrong:
+
+  atomic under packages/ui (recommended)   114 files - atoms/molecules/organisms,
+                                           and this is where the system comes from
+  feature under apps/web-dashboard         900 files - features/, where the app
+                                           consumes it
+\`\`\`
+
+The one they pick becomes a rule that reaches \`CLAUDE.md\`, so **every prompt after this
+knows where a new component goes** - not what the folders are called, but which rung or
+which feature a new file belongs to. Recommend the one the system came from.
+
+**2h. Fonts** - do not ask at all. Report and move on:
+
+\`\`\`
+fonts   Figtree for both display and body - the only family declared
+        (--font-sans, and next/font Figtree in all three root layouts)
+\`\`\`
+
+If a project genuinely declares two families, say which is which and why you paired them that
+way. If it declares one, there is nothing to decide.
+
+**A note on colour swatches.** You cannot paint a hex in this conversation, so the token name
+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.
+
+### 3. Read what arithmetic cannot - and do it in ONE uninterrupted run
+
+Every answer is in hand, so nothing below needs the person. **Do not ask, do not confirm, do
+not narrate the mechanics.** Three lines on screen for the whole phase:
+
+\`\`\`
+1/3  Measuring the repository...            (step 1, already done)
+2/3  Naming the anatomy and validating...   (this step)
+3/3  Sending v1 and v2...                   (step 4)
+\`\`\`
+
+**Narrate findings, never mechanics.** A grep, a glob, a file you opened and ruled out, a draft
+you rewrote - none of those is a finding, and a run that prints them reads as a machine talking
+to itself. *"Their docs call Ocean the primary branding scale"* is a finding and earns its line.
+
+**The census answers first, always.** Before opening any file, check whether \`signals\`, \`sketch\`,
+\`declared\` or \`coverage\` already hold it - they usually do, and a file read whose content the
+census carries is the failure this pipeline keeps paying for. The sketch now runs to 150 nodes,
+so a big component arrives WHOLE: \`TextEditor\` used to lose its editable region at node 60 and
+that single truncation is what forced a hand-read of the file (dono, 01/08).
+
+**Validate in ONE call, at the end.** Build every recipe in memory first, then send them all to
+\`validate_recipes\` - one round trip for the whole reading instead of one per component. A reader
+with 35 anatomies spent 35 turns asking the same question, and none of that was thinking. Only
+after the batch answers do you fix what it named and, if you fixed anything, ask once more.
+
+
 
 Open the project and answer the questions below. Then add a \`reading\` object to
 \`_synthesisui/census.json\`:
@@ -591,6 +782,16 @@ a recipe before these tools existed, and four separate readings were lost in sil
 \`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.
 
+**In ONE call.** Build every recipe in memory, then send the whole reading to
+\`validate_recipes\` - one round trip for 35 components instead of 35. \`validate_recipe\`
+(singular) is for the one recipe you rewrote after the batch named it; reaching for it in a
+loop is the shape this optimisation exists to kill (dono, 01/08).
+
+\`\`\`
+validate_recipes({ recipes: [{ name, recipe }, …] })   the whole reading, one question
+validate_recipe(name, recipe)                          the one you just fixed
+\`\`\`
+
 \`validate_recipe\` never answers yes or no. It answers with what would not survive:
 
 \`\`\`
@@ -748,7 +949,16 @@ scale and lost the sentence (dono, 01/08).
 
 When their docs (a \`Geometry.mdx\`, a design-tokens page, comments beside the \`@theme\`)
 state what a step is FOR, send it as system-wide rules - \`applies: []\`, \`fact: true\`, the
-doc as evidence:
+doc as evidence.
+
+**One doc pass, and only for what the census cannot hold.** A scale's INTENT is prose, so it
+genuinely needs a human sentence somebody wrote - but a scale's VALUES, its token names, the
+theme, the class convention and the architecture are all measured and sitting in \`declared\`,
+\`signals\` and \`conventions\`. Opening a docs page to confirm a number the census already
+carries costs a turn and answers nothing. Read the docs ONCE, for the sentences; never in a
+loop, and never to check arithmetic.
+
+Send it like this:
 
 \`\`\`
 this system's spacing has exactly three steps - sm for close relationships inside a
@@ -786,157 +996,9 @@ The older flat form - \`"parts": [{ "name": "label", "classes": "..." }]\` - sti
 styles correctly. It just carries no shape, so the preview lays the parts out in a row and the
 spec view has no nesting to draw.
 
-### 3. Walk them through the decisions, one at a time
-
-Six 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.
-
-Every question carries **your recommendation first, marked as such**, and the evidence for it in
-one line. They are choosing, not auditing you.
-
-**3a. Source** - the folder you measure the system out of.
-
-Options are the candidates the CLI already ranked, each with what it would produce, plus the
-whole repo, plus *somewhere else* for a path they type:
-
-\`\`\`
-Where should the system come from?
-
-  packages/ui (recommended)    114 files · 47% of its values already named ·
-                               92 tokens of their own · every app imports it
-  the whole repo               2797 files · 36% · the average of one dark app
-                               and two light ones, which is a diagnosis and
-                               not a system
-  apps/web-dashboard           the heaviest consumer, if you want one app's
-                               vocabulary rather than the shared one
-  somewhere else               a path you name
-\`\`\`
-
-If they name a path you cannot use, say which of the two it is and offer the list again:
-
-- **it does not exist**, or holds no files you can read
-- **it holds no design values** - no colours, no radii, no tokens. A folder of server code or
-  config is not a design system, and measuring it produces a system of nothing.
-
-**3b. Name** - suggest theirs, and let Enter take it:
-
-\`\`\`
-What should it be called?  (SignalUI)
-\`\`\`
-
-Say where the suggestion came from - \`Introduction.mdx\`, the package name, the folder. A name
-they recognise is worth more than a clever one. The slug is derived once and never changes, so
-this is the moment.
-
-**3c. Primary** - and explain the role before offering the choice, because *primary* is our word
-and not necessarily theirs:
-
-\`\`\`
-Primary is the colour that carries action - buttons, links, focus, the thing
-you want pressed. Everything else in the system is measured for contrast
-against it.
-
-  #059aed  ocean-500 (recommended)     your ColorPalette.mdx calls Ocean the
-                                       "Primary branding scale"
-  #1a4ed8  royal-blue-500              your docs label this one secondary
-  #ec4899  vivid-pink-500              half of your signature AI gradient
-  #4A90E2  blue-500                    the most-painted blue in the folder,
-                                       but it sits after your own
-                                       /* End - Signal UI */ marker
-\`\`\`
-
-Always name the hex AND the token, and always give the reason a value is *not* recommended when
-frequency would have picked it. That last row is the whole point of asking.
-
-**3d. Default theme** - which face it opens in:
-
-\`\`\`
-  dark (recommended)   data-theme="dark" in the root layout, next-themes
-                       defaultTheme="dark", enableSystem={false}
-  light                the other one, also real here
-\`\`\`
-
-**Two is all there is** - a SynthesisUI system carries one palette and one alternate, and the
-schema is \`"light" | "dark"\`. So this is not "which themes do you support", it is "which one do
-docs and installs open in". If both are real, both get built from their own tokens; this picks
-the face.
-
-**3e. Canvas** - confirm, do not offer a list. The page is measured, not chosen:
-
-\`\`\`
-canvas  #222326  darkgray-500 - what DashboardLayout paints on <main>
-                 (your sidebar sits a step deeper at darkgray-700)
-\`\`\`
-
-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.
-
-**3e-ter. Which architecture has priority** - ask only when the CLI reported more than
-one, which it does under "How this project is organised".
-
-A project having two shapes is not a project with a mistake: a library organised
-atomically inside a monorepo whose apps are organised by feature is two true answers.
-Say that before you ask, or the question reads as an accusation.
-
-\`\`\`
-Two shapes, and neither is wrong:
-
-  atomic under packages/ui (recommended)   114 files - atoms/molecules/organisms,
-                                           and this is where the system comes from
-  feature under apps/web-dashboard         900 files - features/, where the app
-                                           consumes it
-\`\`\`
-
-The one they pick becomes a rule that reaches \`CLAUDE.md\`, so **every prompt after this
-knows where a new component goes** - not what the folders are called, but which rung or
-which feature a new file belongs to. Recommend the one the system came from.
-
-**3f. Fonts** - do not ask at all. Report and move on:
-
-\`\`\`
-fonts   Figtree for both display and body - the only family declared
-        (--font-sans, and next/font Figtree in all three root layouts)
-\`\`\`
-
-If a project genuinely declares two families, say which is which and why you paired them that
-way. If it declares one, there is nothing to decide.
-
-**A note on colour swatches.** You cannot paint a hex in this conversation, so the token name
-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.
+### 4. Send it
 
-Then, and only after all of them are answered:
+Everything is answered and everything is validated:
 
 \`\`\`
 npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--registry <from step 0>]
@@ -947,13 +1009,13 @@ npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--
 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
+asked.** Skip 2a and the first time they learn where their system came from is when they open
 it.
 
 If it refuses, it says which of the three it is: no session, an expired one, or a token issued
 by a different host. All are recoverable from the census on disk; none need a re-measure.
 
-### 4. Tell them exactly what they have, and what is theirs to decide
+### 5. Tell them exactly what they have, and what is theirs to decide
 
 The import publishes **v1** as a faithful baseline and opens a **v2 draft** holding the
 proposal. Say all of this in your own words - do not just print the link:
@@ -984,7 +1046,7 @@ three biggest items so they know whether it is worth opening now.
 found in their code, a token that is not ramp-shaped, a name the document refused. Read them
 and pass on the ones that matter.
 
-### 5. Close the loop in their repo
+### 6. Close the loop in their repo
 
 The system is only worth something once it governs the code it came from:
 
@@ -1022,6 +1084,14 @@ The user should end up with a system that reads like theirs and not like ours:
 - **Do not guess \`themes\` to be helpful.** Omitting it falls back to counting rungs, which is
   a guess the product labels as a guess. A wrong confident answer does not get labelled.
 - **Do not apologise for the empty contracts.** They are the design. Explain them.
+- **Do not come back with a question once step 3 has started.** Everything answerable was
+  answered in step 2. An interruption in the middle of a silent phase costs the person the
+  whole phase, because they now have to hold what you were doing in their head.
+- **Do not narrate the mechanics.** No grep, no glob, no "let me check whether X exists", no
+  draft you rewrote. Findings earn a line; the machine talking to itself does not.
+- **Do not open a file to confirm something the census already carries.** \`signals\`, \`sketch\`,
+  \`declared\`, \`conventions\` and \`coverage\` are the answer to almost every "let me just check".
+- **Do not validate in a loop.** One \`validate_recipes\` for the whole reading.
 
 ## Not yet true
 

package/package.json

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