synthesisui 0.16.61 → 0.16.63

package/dist/skill-import.js

@@ -67,6 +67,23 @@ So if the file says \`"registry": "http://localhost:3000"\`, every command in th
 \`--registry http://localhost:3000\`. If it says production, pass nothing. 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,
+and narrating it - *"registry is production, so no --registry flag needed"* - spends the
+person's attention on a decision that was never theirs (dono, 01/08). Say something only when
+there is nothing to say to: no token, or the wrong host.
+
+## How to narrate
+
+The person cares about **what you found in their code** and **what you are about to create**.
+They do not care which flag you passed, which grep you ran, or what you checked and ruled out.
+
+- Report findings, not mechanics. *"Their docs call Ocean the primary branding scale"* earns
+  its line. *"Let me check whether packages/ui exists"* does not.
+- Every decision you make on their behalf belongs in **one** confirmation at the end, not
+  scattered through the work as fait accompli.
+- Never end on a wall of prose that happens to contain a question. If you need an answer, the
+  last thing on screen is the question.
+
 ### 1. Measure
 
 **Always run from the project root, and always twice in a monorepo.** The root is where the
@@ -149,21 +166,122 @@ about which one is the page. Read a screen and see.
 **\`fonts\` and \`concept\`** - the voice, and one paragraph on what this product is. The concept
 feeds every recommendation downstream, so a real one beats a generic one by a wide margin.
 
-### 3. Send it
+### 3. Walk them through the decisions, one at a time
+
+Four 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.
+
+**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.
+
+Then, and only after all four are answered:
 
 \`\`\`
-npx synthesisui import --census _synthesisui/census.json --name "<their name for it>" [--registry <the one from step 0>]
+npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--registry <from step 0>]
 \`\`\`
 
-**One real write, and it creates a system on their account.** Say what you are about to send
-and what it will be called before you run it.
+**This is the one real write.** Everything before it is on their disk and costs nothing to redo.
 
-The CLI asks for a name unless \`--name\` is passed. It does **not** ask about the scheme when
-your reading already answered - a second question would only be a chance to contradict you.
+Pass every answer explicitly - \`--name\`, \`--scope\` if they changed it, 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
+it.
 
-If it refuses, it will tell you which of the two problems it is: no session, an expired one, or
-a token issued by a different host than the one you are sending to. All three are recoverable
-from the census already on disk; none of them need a re-measure.
+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
 

package/package.json

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