synthesisui 0.16.60 → 0.16.61

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

@@ -69,17 +69,42 @@ mismatch instead of letting the server reject it, but the point is not to reach
 
 ### 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
+\`\`\`
+
+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 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 --dir <the folder that holds the design decisions>
+npx synthesisui import --dry --scope packages/ui
 \`\`\`
 
-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.
+**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.
 
-This writes \`_synthesisui/census.json\` and **sends nothing**. Read that file.
+\`--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
 

package/package.json

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