synthesisui 0.16.138 → 0.16.140

package/dist/anatomy-read.js

@@ -65,9 +65,24 @@ const FRONTIERS = new Set(["component", "external"]);
  * its own box, because its styles already sit on the component's base.
  */
 const STRUCTURAL = /^(root|wrapper|base|el|outer)$/i;
-/** A pathological transcription of somebody's DOM, bounded. Six levels reaches
- *  any real component; past that it is layout divs all the way down. */
-const MAX_DEPTH = 6;
+/**
+ * A transcrição patológica do DOM de alguém, com teto - e o teto foi medido errado.
+ *
+ * "Seis níveis alcançam qualquer componente real; além disso são divs de layout até o fim" foi
+ * calibrado numa biblioteca de 36 componentes. Um app de 275 desmente: a leitura do
+ * `apps/web-dashboard` tem 64 nós além do 6, e a distribuição mostra que a cauda é fina e é
+ * CONTEÚDO (05/08):
+ *
+ *     nível  0    1    2    3    4    5    6    7   8  9
+ *     nós  923  935  871  609  405  231  139   50  12  2
+ *
+ * O que estava acontecendo com esses 64: `walk` retornava ali, então tudo abaixo do sexto nível era
+ * descartado em silêncio - a estrutura que o cliente escreveu, perdida sem uma linha de aviso.
+ *
+ * 10 cobre a população inteira com folga e mantém o teto contra recursão patológica, que é a razão
+ * de ele existir. Um número medido em vez de estimado.
+ */
+const MAX_DEPTH = 10;
 /**
  * The same ceiling the sketch measured, for the same reason.
  *

package/dist/skill-import.js

@@ -74,6 +74,31 @@ and narrating it - *"registry is production, so no --registry flag needed"* - sp
 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.
 
+### 0b. ASK THE REGISTRY WHAT EXISTS - never your notes
+
+If your memory says this repo already produced a system, **verify it before you say it out loud**,
+and verify it per SLUG:
+
+\`\`\`
+curl -s -o /dev/null -w "%{http_code}" <registry>/api/registry/ds/<slug>
+\`\`\`
+
+\`404\` means it does not exist. \`200\` means it does. That is the whole check, and it costs one call.
+
+**\`synthesisui list\` does NOT answer this.** It returns the public gallery - 13 systems, none of
+them private - so a private system of theirs is invisible to it and a \`list\` that does not mention
+\`their-slug\` proves nothing.
+
+This exists because of a real run (dono, 05/08). The owner had deleted every system on his account,
+and the skill opened with *"my notes from the previous twelve runs say this repo has already
+produced two published systems"* - then offered three options built on that: upgrade a slug the
+registry answers \`404\` for, avoid a name collision that no longer existed, and warn that a \`--dry\`
+would wipe files it does not touch. One \`curl\` would have replaced all of it.
+
+**A memory may report the past; it may never assert the present.** *"The last run produced
+\`signalui\`"* is a fine sentence. *"This repo has two published systems"* is a claim about the server,
+and the server is the only thing that can make it.
+
 ## How to narrate
 
 The person cares about **what you found in their code** and **what you are about to create**.
@@ -880,6 +905,13 @@ Copying \`dark\` in at the top level of a recipe costs you that block, silently,
 component that has one - and \`import\` already converts it for the recipes IT writes, so the
 only place this can be lost is a recipe you hand-built (not-expressed.md, dono, 03/08).
 
+**Which means: do NOT pre-convert the dark half inside \`looks[X]\`.** The conversion already
+happens on the way in, so adding a \`scheme: "dark"\` layer to the census's own look while leaving
+the \`dark\` key in place produces the SAME layer twice - measured at 28 components in one real
+import, with the properties in a different key order so it did not even look like a duplicate
+(dono, 05/08). \`validate_recipe\` telling you a top-level \`dark\` would be dropped is true about a
+RECIPE and says nothing about the reading: you send a reading, and the reading's \`dark\` is read.
+
 **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
@@ -1157,15 +1189,40 @@ 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.
 
+**And the notes now judge YOUR reading, which nothing did before.** \`validate_recipes\` looks at
+the \`anatomy\` inside a recipe; the anatomy you author travels in \`reading.components[X].anatomy\`,
+and until 05/08 no one looked at it - so a note may name findings the batch validator never saw.
+Two kinds, and both are yours to act on:
+
+- **structure that does not survive the reader.** Nine of these landed on a real import, every one
+  the same shape: a \`button\` holding a \`stack\`. Only \`row\` and \`stack\` arrange, so the children are
+  hoisted out and become siblings - the nesting they wrote is gone. Fix it in the reading and send
+  again; the note tells you the component and the path.
+- **references pointing at components the system does not contain.** 215 of 660 on that same
+  import. This one is usually NOT a mistake of yours: their component composes something the gate
+  left out, or something outside the scope that was measured. Say the number to the person and name
+  the top few, because a specimen there draws the reference and nothing else - and if the missing
+  piece is central to their system, the answer is a wider \`--scope\`, not a rewritten reading.
+
 ### 6. Close the loop in their repo
 
 The system is only worth something once it governs the code it came from:
 
 \`\`\`
-npx synthesisui upgrade <slug> [--registry …]   # brings the contract in
+npx synthesisui add <slug> [--registry …]       # INSTALLS it: writes _synthesisui/ds/<slug>/
 npx synthesisui doctor [paths…]                 # the contract starts being enforced
+npx synthesisui upgrade <slug> [--registry …]   # LATER, when a new version is published
 \`\`\`
 
+**The order is not a preference: \`upgrade\` reads the \`.lock\` of an installed DS and refuses
+without one** - \`"<slug>" is not installed here - run \\\`synthesisui add <slug>\\\` first.\` So
+offering \`upgrade\` to somebody who has never installed hands them a command that fails on contact
+(dono, 05/08). Check for \`_synthesisui/ds/<slug>/.lock\` before you recommend either one.
+
+And say what each writes, because one of them rewrites code: \`add\` and \`upgrade\` write inside
+\`_synthesisui/\`, and \`upgrade\` ALSO regenerates components - but only files carrying the
+\`Generated by SynthesisUI\` header, so their own components are never touched.
+
 \`doctor\` is where the promise pays off: every design value written by hand, the token their
 own system already has for it, and the components used outside the axes their contract
 declares. In a monorepo, scope it per app - one system, N consumers.
@@ -1186,8 +1243,16 @@ The user should end up with a system that reads like theirs and not like ours:
 
 ## What to resist
 
+- **Do not let memory speak for the server.** Notes report the past; a claim about what exists
+  now needs the one \`curl\` in step 0b. Four statements in one real run were wrong this way, and
+  every option offered on top of them was wrong too (dono, 05/08).
 - **Do not run \`import\` without \`--dry\` to explore.** It creates a real system on their
   account. Measure with \`--dry\`, read, then send once.
+- **\`--dry\` does not delete anything.** It writes \`census.json\` and creates the folder if needed -
+  there is no \`rm\` in the import path. What it DOES do is overwrite that one file, so a reading
+  injected into it is lost; everything else under \`_synthesisui/\` (the config, \`ds/<slug>/\`, the
+  hook's marker, \`not-expressed.md\`) survives untouched. Telling somebody a measure will wipe their
+  install talks them out of a safe command (dono, 05/08).
 - **Do not redo the arithmetic.** If you find yourself counting colours, you are in the wrong
   half of the pipeline.
 - **Do not fill \`roles\` with what looks nice.** It is a reading of what their code already

package/package.json

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