synthesisui 0.16.94 → 0.16.96

package/dist/anatomy-read.js

@@ -100,7 +100,10 @@ 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) {
+root, 
+/** This component's sketch, so a node can name its classes by INDEX instead
+ *  of retyping them - see `AnatomyRead.at`. */
+sketch) {
     const parts = {};
     const composes = [];
     const external = [];
@@ -189,9 +192,16 @@ root) {
                 if (key !== wanted) {
                     notes.push(`two parts named \`${wanted}\` - the second is \`${key}\``);
                 }
-                const classes = typeof node.classes === "string"
-                    ? node.classes.split(/\s+/).filter(Boolean)
-                    : [];
+                /**
+                 * THE CENSUS'S OWN STRING WINS when the node points at it. A retyped
+                 * list is a copy that can lose a modifier; an index cannot.
+                 */
+                const raw = typeof node.classes === "string"
+                    ? node.classes
+                    : typeof node.at === "number"
+                        ? (sketch?.[node.at]?.classes ?? "")
+                        : "";
+                const classes = raw.split(/\s+/).filter(Boolean);
                 const t = transcribe(classes, declared);
                 parts[key] = { base: t.base, dark: t.dark, states: t.states };
                 /**

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";
 /**
@@ -1656,7 +1656,10 @@ async function resolveReadParts(census, root) {
     for (const [component, entry] of Object.entries(read)) {
         const anatomy = entry?.anatomy;
         const resolved = Array.isArray(anatomy) && anatomy.length > 0
-            ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root)
+            ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root, 
+            // The component's own sketch, so a node naming itself by index reads
+            // the exact class string the census measured (dono, 01/08).
+            looks[component]?.sketch)
             : Array.isArray(entry?.parts) && entry.parts.length > 0
                 ? resolveFlatParts(entry.parts, declared)
                 : null;
@@ -1797,9 +1800,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 } : {}),
@@ -1882,6 +1893,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/commands/upgrade.js

@@ -7,6 +7,7 @@ import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
+import { doctor } from "./doctor.js";
 /**
  * The highest `v<n>` below `installed` among the folder names given, or the one
  * asked for. Pure, so the version arithmetic can be tested without a disk.
@@ -226,6 +227,26 @@ export async function upgrade(slug, opts) {
         console.log("");
         console.log(body(`⚠ Could not regenerate: ${failed.join(", ")} (removed/renamed in v${latest.version}?)`));
     }
+    /**
+     * THE CHECK RUNS ITSELF - closing the loop the owner asked for end to end
+     * (dono, 01/08).
+     *
+     * An upgrade that lands a v2 whose whole point is "these literals are tokens
+     * now" and then says "ask your agent to migrate" leaves the person with no
+     * way to know whether it worked. The doctor is the answer and it is one
+     * command, so it is not somebody's job to remember: it runs here, over the
+     * same root, and its report IS the receipt.
+     *
+     * Never strict. A finding is information, not a failure of the upgrade, and
+     * exiting non-zero on somebody's own drift would turn a successful install
+     * into a red terminal.
+     */
+    console.log(section("Checking the app against v" + latest.version));
+    await doctor({ dir: root }).catch((err) => {
+        // A doctor that cannot run is not an upgrade that failed - the artifacts
+        // are already on disk and correct.
+        console.log(body(`The check could not run (${err instanceof Error ? err.message : "unknown"}). Run \`npx synthesisui doctor\` when you can.`));
+    });
     console.log(section("Migrate the app"));
     console.log(body(`The migration brief is at _synthesisui/ds/${slug}/UPGRADE.md`));
     console.log("");

package/dist/doctor/sketch.js

@@ -19,8 +19,23 @@
  * 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=\{?["'`]([^"'`{}$]*)["'`]\}?/;
 /**

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\`:
@@ -182,14 +373,14 @@ Open the project and answer the questions below. Then add a \`reading\` object t
   "components": {
     "MetricCard": {
       "anatomy": [
-        { "as": "icon", "name": "icon", "classes": "size-8 text-ocean-500" },
+        { "as": "icon", "name": "icon", "at": 1 },
         {
           "as": "stack",
           "name": "body",
-          "classes": "flex flex-col gap-1",
+          "at": 2,
           "children": [
-            { "as": "text", "name": "label", "classes": "text-xs uppercase text-lightgray-500" },
-            { "as": "heading", "name": "value", "classes": "text-2xl font-bold" }
+            { "as": "text", "name": "label", "at": 3 },
+            { "as": "heading", "name": "value", "at": 4 }
           ]
         }
       ]
@@ -197,15 +388,15 @@ Open the project and answer the questions below. Then add a \`reading\` object t
     "ArticleCard": {
       "root": "Card",
       "anatomy": [
-        { "as": "image", "name": "cover", "classes": "aspect-video w-full rounded-t-lg" },
-        { "as": "heading", "name": "title", "classes": "text-lg font-semibold" },
+        { "as": "image", "name": "cover", "at": 1 },
+        { "as": "heading", "name": "title", "at": 2 },
         { "as": "component", "ref": "TextEditor" },
         {
           "as": "row",
           "name": "footer",
-          "classes": "flex items-center gap-2 border-t p-3",
+          "at": 3,
           "children": [
-            { "as": "button", "name": "publish", "classes": "btn btn-primary" },
+            { "as": "button", "name": "publish", "at": 4 },
             { "as": "button", "name": "discard", "classes": "btn btn-ghost" }
           ]
         }
@@ -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:
 
 \`\`\`
@@ -701,9 +902,22 @@ file for, minus the one thing that is genuinely yours: the NAMES.
 
 Read that and write the anatomy: depth 1 is \`trigger\`, the dot is \`status-dot\`, the
 capitalised tag is a frontier. **Do not open the component file** - if the sketch is
-missing or visibly truncated (60-node cap), say so in not-expressed.md and only then
+missing or visibly truncated (150-node cap), say so in not-expressed.md and only then
 read, because that gap is the census's to close.
 
+**NAME THE NODE BY ITS INDEX - never retype the class string.** Each anatomy node carries
+\`"at": <index into this sketch>\`, and the CLI reads the exact string the census measured:
+
+\`\`\`json
+{ "as": "button", "name": "trigger", "at": 1 }
+\`\`\`
+
+Retyping is where a modifier goes missing. Six real components arrived with \`hover:\` and
+\`focus:\` in their source and no state at all in the recipe, and the parser was not the
+problem - the copy was (audit, dono, 01/08). An index cannot lose a class. \`classes\` still
+works and still wins when you send both, which is for the one node the sketch could not
+reach; every other node uses \`at\`.
+
 ### What the CLI now reads for you, so do not spend a turn on it
 
 **The rule under all of this: you are given EVIDENCE and asked to DECIDE.** You are never
@@ -748,7 +962,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 +1009,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 +1022,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 +1059,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 +1097,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.94",
+  "version": "0.16.96",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {