synthesisui 0.16.141 → 0.16.145

package/dist/skill-init.js

@@ -0,0 +1,226 @@
+/**
+ * A SKILL DA PRIMEIRA CORRIDA, como o CLI a distribui.
+ *
+ * Mesmo motivo do `skill-import.ts`: o build é `tsc` e nada mais, então um `.md` precisaria de um
+ * passo de cópia que pode silenciosamente não rodar. Um módulo TypeScript não pode falhar em ser
+ * empacotado.
+ *
+ * ESTA É A FONTE. A cópia em `.claude/skills/` é o que o nosso editor lê, e o spec assere que as duas
+ * são idênticas - então divergência fica vermelha em vez de embarcar uma skill que descreve um fluxo
+ * que o produto não tem.
+ *
+ * E ela é instalada pelo `connect` junto com a de import, de propósito: uma skill que exige reiniciar
+ * o editor para aparecer é uma skill que ninguém usa na primeira corrida, que é a única em que ela
+ * serve (dono, 05/08).
+ */
+export const INIT_SKILL = `---
+name: sui-init
+description: The first run - wire the agent, choose what to import, and hand back a system that is already optimised. Use when somebody has just installed SynthesisUI and has no system yet ("/sui-init", "set me up", "começar", "importar meu projeto"). Asks everything up front, measures while asking, and ends in four lines.
+---
+
+# The first run
+
+One conversation, and at the end they have a design system built out of their own code, with our
+optimisations applied and a way back to the untouched version.
+
+The purpose that decides every tie below: **read their repository and give it back as recipes with
+visual, semantic and functional parity, without supposing and without inventing anything.**
+
+\`CLAUDE.md\` rules. When the two disagree, this file is the one that is out of date.
+
+---
+
+## THE SHAPE OF THIS RUN, AND WHY IT IS THIS SHAPE
+
+Four questions, asked before anything that needs an answer. Then silence, then four lines.
+
+\`\`\`
+1  environment      which agent they work in - and what that agent can actually get
+2  authorisation    may we optimise after importing, and which parts
+3  project          WHICH folder becomes the system (the only unavoidable choice)
+4  identity         name, primary, theme - each already answered by the census
+---- nobody waits from here on ----
+   import v1  ->  freeze v1  ->  apply what they authorised  ->  four lines
+5  offer            put the tokens back into their code
+\`\`\`
+
+**Every question is asked before the work, and the work starts during the questions.** A person who
+answers four things in ninety seconds and then watches one bar has had a good four minutes; the same
+person interrupted twice mid-silence has had a bad twenty (dono, 01/08).
+
+**What runs in parallel, precisely.** The UNSCOPED census - \`npx synthesisui import --dry\` - needs no
+answer and discovers the candidate projects, so start it the moment question 1 is on screen. The
+SCOPED census needs question 3, and no amount of wishing makes it earlier. Do not promise more
+parallelism than that: a progress bar waiting on a person is worse than a question.
+
+---
+
+## 1. ENVIRONMENT
+
+Ask, because it changes what you install and it changes what you promise. Do not pretend the answers
+are equivalent - they are not, and a Design System Lead spots that in one minute.
+
+\`\`\`
+Which agent do you work in?
+
+  Claude Code (recommended if you have it)
+      rules + 11 tools + THE CHECK: after every file write, a hook measures what you
+      wrote and hands the result back into the conversation. No other agent has this.
+  Cursor
+      rules (.cursor/rules) + the same 11 tools (.cursor/mcp.json). No post-write check -
+      Cursor has no hook that feeds context back, so the rules are read, not enforced.
+  Something else
+      rules in AGENTS.md, which most agents read. Tell me which one and I will say
+      honestly whether its tool format is one we know.
+\`\`\`
+
+**Never invent a config path.** If they name an agent whose format is not in that list, say so and
+write \`AGENTS.md\` only. Writing a file into the wrong place is worse than not writing it: it looks
+like support and delivers nothing.
+
+Then wire it, once, with the command that is already idempotent:
+
+\`\`\`
+npx synthesisui@latest connect
+\`\`\`
+
+## 2. AUTHORISATION - ONE QUESTION, THREE BOXES
+
+Ask it HERE, before the import, because it is the only way the end can be four lines instead of a
+negotiation.
+
+\`\`\`
+After I import, may I apply the deterministic fixes? Nothing here is AI - it is arithmetic,
+and your untouched version stays frozen either way.
+
+  [x] tokens & contrast   values that repeat become one named token; text that fails
+                          contrast gets its INK changed, never its background
+  [x] spacing             lengths off your own scale converge onto the step you named
+  [x] typography          sizes and weights land on your own scale
+\`\`\`
+
+All three checked by default. Two things must be said in the same breath, because a default that
+edits is only defensible with both:
+
+- **v1 is frozen before anything is applied.** It is a published version, it never moves, and
+  restoring it is one click.
+- **Value, never form.** Your axes, options, parts and layers are declarations - we do not touch
+  them. \`archetypeFidelity\` is excluded from this run on purpose: its fix once deleted the \`variant\`
+  and \`size\` a real \`Input\` declared (dono, 02/08).
+
+If they decline all three: fine, and say what they are choosing - the system arrives exactly as
+their code has it, and the optimisations wait on a button.
+
+## 3. PROJECT
+
+By now the unscoped census has finished, so this is a list and not a question in the dark. The CLI
+already ranks the candidates by how many tokens each declares - use its numbers, never your
+impression.
+
+\`\`\`
+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
+\`\`\`
+
+**Do not ask which styling they use.** We measure it, and better than they can answer it: the census
+counts every form with a percentage and an example. Show it instead, and name what we cannot read:
+
+\`\`\`
+Measured across 2797 files: 46% Tailwind classes, 31% CSS Modules, 12% sx props.
+I read all three. What I do not read yet: styled-jsx, 3% - and I will say so in the report.
+\`\`\`
+
+A wrong answer from them would override a right measurement from us. That is the whole reason this is
+a statement and not a question.
+
+## 4. IDENTITY
+
+Name, primary, default theme, canvas. Every one of them is already answered by the census - ask them
+as separate selectable questions, recommendation first, evidence in one line. The full wording lives
+in the \`sui-import-ds\` skill; do not reinvent it here, and do not ask anything it does not.
+
+**Our kit is not a question.** A project with its own component library gets theirs alone.
+
+---
+
+## THE SILENT PART
+
+Now nobody is asked anything. In order:
+
+\`\`\`
+1  npx synthesisui import --scope <theirs> --usage <apps…>     measures with the answers
+2  the reading                                                  anatomy, rules, roles
+3  send it                                                      their v1 exists
+4  POST /api/registry/ds/<slug>/optimize                        freeze v1, apply what they said yes to
+       { "categories": ["tokens", "spacing", "typography"] }
+\`\`\`
+
+Step 4 is ONE call on purpose: it freezes the base and applies the fixes in the same request, so
+there is never a moment where an optimisation landed with no frozen version to go back to.
+
+To show the numbers BEFORE applying - useful when they hesitated on question 2 - the same route
+answers a probe and writes nothing:
+
+\`\`\`
+{ "probe": true, "categories": ["tokens"] }
+\`\`\`
+
+If they authorised nothing, skip step 4 entirely. Do not call it with an empty list to be tidy: it
+answers 400, and a 400 in a first run reads as a broken product.
+
+---
+
+## 5. THE FOUR LINES
+
+This is the whole point of the run. Four lines, their numbers, no adjectives.
+
+\`\`\`
+SignalUI is yours - 275 components and 92 of your own tokens, read out of packages/ui.
+
+v1 is frozen: your system exactly as your code has it today. It never moves.
+v2 is what you are looking at - the same system with 118 deterministic fixes: contrast on
+text only, lengths onto your own scale, near-identical colours unified.
+
+Back to v1 is one click: /dashboard/mine/signalui/publish
+\`\`\`
+
+**What must never be in those lines:** how many files we scanned, how long it took, which readers
+ran, what the ledger says. All of that is in the report and none of it is what somebody wants in the
+first minute of owning a system.
+
+**What must always be there:** the count of their components, the count of their own tokens, and the
+way back.
+
+## 6. THE OFFER
+
+One question, and only if there is something to offer - the doctor already knows the number.
+
+\`\`\`
+340 hand-written values in your code have a token in your system now.
+Want me to replace them? It only touches values your system names, and you read the diff.
+
+    npx synthesisui@latest doctor --fix
+\`\`\`
+
+If the number is zero, say nothing. An offer with no subject is noise, and this run ends better
+short.
+
+---
+
+## WHAT THIS RUN NEVER DOES
+
+- **Never asks a question the census answers.** Styling, coverage, which files exist, how many
+  components - those are measurements, and asking invites a wrong answer to beat a right one.
+- **Never installs a file for an agent they did not name.** \`.cursor/\` in a repo that has no Cursor
+  is the first thing somebody deletes angrily.
+- **Never applies an optimisation without a frozen v1**, and never reports one without the way back.
+- **Never claims parity between agents.** The post-write check exists in one of them. Saying
+  otherwise is the kind of sentence that ends a trial.
+- **Never ends long.** If the last screen needs scrolling, the run failed at the last step.
+`;
+export const INIT_SKILL_PATH = ".claude/skills/sui-init/SKILL.md";

package/package.json

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