synthesisui 0.16.60 → 0.16.62

package/dist/commands/import.js

@@ -637,11 +637,11 @@ async function sayIfWorkspace(root) {
     console.log("");
     if (shared.length > 0) {
         console.log(body("The shape that works, if your vocabulary is shared:"));
-        console.log(body(`    ${paint.strong(`synthesisui import --dir ${shared[0]}`)}   ${paint.faint("the system comes from here")}`));
+        console.log(body(`    ${paint.strong(`synthesisui import --scope ${shared[0]}`)}   ${paint.faint("the system comes from here")}`));
     }
     else {
         console.log(body("The shape that works:"));
-        console.log(body(`    ${paint.strong(`synthesisui import --dir ${apps[0]}`)}   ${paint.faint("one app, one vocabulary")}`));
+        console.log(body(`    ${paint.strong(`synthesisui import --scope ${apps[0]}`)}   ${paint.faint("one app, one vocabulary")}`));
     }
     for (const app of apps.slice(0, 3)) {
         console.log(body(`    ${paint.dim(`synthesisui doctor ${app}`)}   ${paint.faint("how far this one is from it")}`));
@@ -863,6 +863,16 @@ function sayReach(c) {
 }
 export async function runImport(opts) {
     const root = opts.root ?? process.cwd();
+    /**
+     * WHAT TO READ, as opposed to WHERE TO WRITE. In a monorepo the design
+     * 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()
+        .replace(/^\.\/+/, "")
+        .replace(/\/+$/, "");
+    const readFrom = scope ? join(root, scope) : root;
     // A census handed to us (an agent annotated it) is sent as-is; the numbers
     // inside were still ours to begin with.
     let census;
@@ -889,15 +899,20 @@ export async function runImport(opts) {
     }
     else {
         console.log(section("Reading your project"));
-        census = await takeCensus(root);
+        census = await takeCensus(readFrom);
+        if (scope)
+            census.scope = scope;
     }
     summarize(census);
-    if (!opts.census)
+    // Only when nobody has scoped yet. Telling someone to scope to the folder
+    // they just scoped to reads as the tool not having noticed.
+    if (!opts.census && !scope)
         await sayIfWorkspace(root);
-    // A census handed to us is written BACK TO ITSELF. Deriving the path from the
-    // root instead planted a second census at the repo root when the real one
-    // lived in `packages/ui/_synthesisui/` - two files, silently disagreeing
-    // about which import happened (dono, 31/07).
+    // A census handed to us is written BACK TO ITSELF; one we took lands at the
+    // ROOT, whatever it measured. Everything else in `_synthesisui/` is anchored
+    // there - config, `ds/<slug>/`, the hook's marker - and the census was the
+    // only artefact that travelled with `--dir`, which is how two of them ended
+    // up disagreeing about which import happened (dono, 31/07).
     const out = opts.census ?? join(root, "_synthesisui", "census.json");
     await mkdir(dirname(out), { recursive: true });
     await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");

package/dist/index.js

@@ -41,7 +41,7 @@ Usage - deterministic, FREE:
 
 Usage - governance (deterministic, FREE):
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
-  synthesisui import [--dry] [--name <n>]  read the app you already have and make it a system
+  synthesisui import [--dry] [--scope <p>]  read the app you already have and make it a system
                                            your agent follows - without touching your CSS
   synthesisui connect                      wire your agent: the check as an editor hook, the system
                                            as MCP tools, and a contract that stops repeating itself
@@ -66,6 +66,7 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
+  --scope <path>     import: measure only this folder; the census still lands at the root
   --scheme <s>       dark|light - which end of your ladder is the default
   --target <t>       template/init target: next | general (default: next)
   --pages-dir <dir>  init: folder for generated pages (default: app)
@@ -162,6 +163,8 @@ async function main() {
                 name: typeof flags.name === "string" ? flags.name : undefined,
                 // Only these two words. Anything else is a typo that would silently
                 // invert a system, so it falls through to being measured and asked.
+                // WHAT to read. `--dir` stays WHERE the project is, in every command.
+                scope: typeof flags.scope === "string" ? flags.scope : undefined,
                 scheme: flags.scheme === "dark" || flags.scheme === "light"
                     ? flags.scheme
                     : undefined,

package/dist/skill-import.js

@@ -67,19 +67,61 @@ 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
+governance lives - \`_synthesisui/config.json\`, \`ds/<slug>/\`, and the census. One root, one
+census; re-measuring overwrites it rather than leaving copies to send the wrong one.
+
+First, unscoped, to find out what kind of repo this is:
+
 \`\`\`
-npx synthesisui import --dry --dir <the folder that holds the design decisions>
+npx synthesisui import --dry
 \`\`\`
 
-In a monorepo that folder is almost never the repo root. Look for the package every app
-imports from - \`packages/ui\`, \`packages/design-system\`, \`libs/shared-ui\`. The CLI names the
-candidates and ranks them by how many tokens they declare; if it printed a workspace summary,
-read it before choosing. Scoping to the wrong folder measures the wrong thing, and the score
-it reports will be meaninglessly low.
+If it is a single app, that census is the one. If it holds several projects, the CLI says so
+and **names the candidates itself**, ranked by how many tokens each declares:
 
-This writes \`_synthesisui/census.json\` and **sends nothing**. Read that file.
+\`\`\`
+This root holds several projects
+  3 apps (apps/web-admin, apps/web-dashboard, apps/web-review) - and this census
+  is the average of all of them. That is a fine DIAGNOSIS and a poor system: a
+  light app and a dark one average into a palette that is neither.
+
+      synthesisui import --scope packages/ui   the system comes from here
+\`\`\`
+
+Then measure again, narrowed:
+
+\`\`\`
+npx synthesisui import --dry --scope packages/ui
+\`\`\`
+
+**Do not import the average.** Three apps measured together produce a palette that belongs to
+none of them, and it will look plausible - a real monorepo reported 36% coverage across 2797
+files at the root and 47% across 114 in its shared package. The second number is the system;
+the first is a diagnosis.
+
+\`--scope\` narrows what is READ. The census still lands at \`<root>/_synthesisui/census.json\`
+and records what it measured, so you always send the same path and there is never a second
+file to pick between. Nothing is sent by \`--dry\`. Read the file.
 
 ### 2. Read what arithmetic cannot
 
@@ -124,21 +166,43 @@ 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. Confirm once, then send
+
+You have made three decisions on their behalf by now - **where** you measured, **what** it will
+be called, and **which values** carry which meaning. Put all three in one place and ask. Not a
+report that contains a question at the bottom: a question.
+
+Offer the alternatives you actually considered, so choosing is a choice and not a veto:
+
+\`\`\`
+I'd create a system from packages/ui, called SignalUI, opening dark.
+
+  from      packages/ui   114 files, 47% of its values already named
+            (apps/web-dashboard, apps/web-review and apps/web-admin
+             are the consumers; measuring all of them gave 36%, which
+             is the average of a light app and two dark ones)
+  called    SignalUI      their own name, from Introduction.mdx
+  brand     #059aed       their docs call Ocean the primary scale
+  opens     dark          data-theme="dark" in the root layout
+
+This creates it on your account. Go ahead, or change any of these?
+\`\`\`
+
+Then, and only after they answer:
 
 \`\`\`
-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.
+The CLI asks for a name unless \`--name\` is passed, and it does **not** ask about the scheme when
+your reading already answered - a second question would only be a chance to contradict you. So
+if you skip the confirmation above, nobody is asked about the scope at all, 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.60",
+  "version": "0.16.62",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {