synthesisui 0.16.235 → 0.16.239

package/dist/skill-init.js

@@ -1,325 +1,15 @@
 /**
- * A SKILL DA PRIMEIRA CORRIDA, como o CLI a distribui.
+ * O STUB DA SKILL - o corpo é SERVIDO, não embarcado (R1, dono 16/08).
  *
- * 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.
+ * O playbook inteiro morava aqui (15 KB) e, por consequência, no tarball
+ * público do npm e no repo de cada cliente em texto plano. Ele mudou para a
+ * plataforma (apps/web/src/lib/ds/playbooks.ts, gêmeo por spec do
+ * `.claude/skills/sui-init/SKILL.md`) e é servido pelo catalogue autenticado -
+ * a mesma doutrina de sempre: SERVED, NOT SHIPPED. O agente busca o sumário
+ * e depois SÓ o capítulo do passo em que está (a dieta de contexto).
  *
- * 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).
+ * O frontmatter fica INTEIRO no stub: é a description que faz a skill ser
+ * invocada, e ela não é segredo - a esteira é.
  */
-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
-
-Five 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
-5  intent           adopting the system, or migrating design INTO it
-                    (+ where absorbed values live, only if they are migrating)
----- nobody waits from here on ----
-   init  ->  import  ->  freeze  ->  apply what they authorised  ->  four lines
-6  offer            the two lines that wire it up
-\`\`\`
-
-**Every question is asked before the work, and the work starts during the questions.** A person who
-answers five 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, AND IT IS A SINGLE CHOICE
-
-Ask it HERE, before the import, because it is the only way the end can be four lines instead of a
-negotiation.
-
-**ASK IT AS A SINGLE CHOICE, NEVER A MULTI-SELECT.** The first real run of this skill made the reason
-obvious (dono, 05/08): a multi-select renders as three checkboxes plus a fourth, \`[ ] Type something\`,
-that the question tool always appends - and free text next to three closed deterministic transforms
-has nothing to act on. Whatever somebody types there matches no transform that exists, so the option
-is either ignored or it lies. Three named options and the escape stays meaningful.
-
-\`\`\`
-May I apply the deterministic fixes after importing? Nothing here is AI - it is arithmetic,
-and the version you have now stays frozen either way.
-
-  All three (recommended)
-      tokens & contrast - values that repeat become one named token, and text that fails
-      contrast gets its INK changed, never its background
-      spacing - lengths off your own scale converge onto the step you named
-      typography - sizes and weights land on your own scale
-  Let me pick
-      then, and only then, ask which ones - there the multi-select is the right shape,
-      because picking IS the question
-  None
-      the system arrives exactly as your code has it, and the fixes wait on a button
-\`\`\`
-
-Two things must be said in the same breath with the recommendation, because a default that edits is
-only defensible with both:
-
-- **The version they have now is frozen before anything is applied.** It becomes a published version,
-  it never moves, and restoring it is one click. Say the NUMBER the route answers with, never "v1":
-  a system publishes its baseline at birth, so an import writes into v2 and the freeze produces v3.
-- **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.
-
----
-
-## 5. INTENT
-
-The one question the census cannot answer, and the only one whose answer changes what a later command
-puts first.
-
-\`\`\`
-What are you doing with this system?
-
-  Adopting it (recommended)   make the code use the system. The doctor leads with the
-                              values your system already names - those have a one-line
-                              fix, and \`doctor --fix\` does them.
-  Migrating into it           you are moving design out of your apps and into the shared
-                              package. The doctor leads with the values your system does
-                              NOT name yet, by frequency - those are the tokens the
-                              library still has to absorb.
-\`\`\`
-
-Both lists exist in both modes. The answer decides the ORDER, and the order decides what somebody
-does first - measured on a real monorepo (dono, 06/08): with no intent declared, four of the five
-suggestions came out of a consumer app, led by a colour that does not belong to the system's palette
-at all. The same number is noise under one intent and the strongest candidate in the repo under the
-other.
-
-Pass the answer straight through:
-
-\`\`\`
-npx synthesisui@latest init --intent adopt      (or --intent migrate)
-\`\`\`
-
-**One follow-up, and ONLY when they chose migrating.** Absorbing is what a migration does; asking an
-adopter where absorbed values would go is asking about a command they will not run this month.
-
-\`\`\`
-When your system absorbs a value, where should it live?
-
-  In the system (recommended)   it becomes a token of the design system, and the
-                                tokens.css it generates starts emitting it
-  In your own CSS               we hand you the block and you paste it into your
-                                vocabulary; the next import reads it back as a
-                                token you declared
-\`\`\`
-
-Then \`--absorb system\` or \`--absorb code\` on the same \`init\`. Both answers are real: the second exists
-because in some teams the canonical vocabulary IS their stylesheet, and in that case our part is to hand
-over the snippet - never to write in their file.
-
-**Run \`init\` even when nothing else needs it.** It writes \`_synthesisui/config.json\` - the committed
-file that holds \`target\`, \`pagesDir\`, \`componentsDir\`, \`styles\` and this intent - and until 06/08 this
-run never called it: a full first run left no config at all, so \`template\` and \`component\` fell back to
-defaults and the intent had nowhere to live (dono, 06/08).
-
----
-
-## THE SILENT PART
-
-Now nobody is asked anything.
-
-**Steps 1 to 3 are NOT described here. Invoke the \`sui-import-ds\` skill and let it drive them.**
-
-That skill owns the import: the double measurement and why a library measured alone reports no laws,
-the \`--scope\` versus \`--usage\` split and the two mistakes it exists to prevent, the whole shape of the
-reading - anatomy, rules with \`kind\`/\`applies\`/\`fact\`, \`typeRoles\`, themes read from the switch rather
-than from the palette - the single batched \`validate_recipes\` call, and what to do with a 401. It is
-over a thousand lines of specifics, every one of them paid for by something that went wrong.
-
-Paraphrasing three of those lines here is how the two files start describing different pipelines, and
-the paraphrase always loses: an agent following a summary does a shallow import and nobody can see
-which document was wrong. So this skill asks the questions and hands the answers over:
-
-\`\`\`
-Invoke: sui-import-ds
-Already decided, do not ask again:
-  source   <the folder they picked in question 3>
-  usage    <the apps the CLI named, if any>
-  name · primary · theme · canvas · architecture   <what they answered in question 4>
-  standards   none, if they have a component library of their own
-Then come back here for step 4.
-\`\`\`
-
-Then, and only then, the part that belongs to this skill:
-
-\`\`\`
-4  POST /api/registry/ds/<slug>/optimize      freeze v1, apply what they authorised
-       { "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.
-
----
-
-## 6. THE FOUR LINES
-
-This is the whole point of the run, and **it is not yours to compose.** Run this and print nothing
-else:
-
-\`\`\`
-npx synthesisui@latest summary <slug> --base <base> --draft <draft> --fixes <how many>
-\`\`\`
-
-It prints their component count, their own token count, where the system was read from, the two
-versions with the way back, and the one thing to do next. The numbers for \`--base\` and \`--draft\` come
-from the \`optimize\` RESPONSE - never invented here, because the platform is what numbers a version.
-
-**Why a command instead of four lines you write.** The last screen of this run has ended long, more
-than once - up to four hundred words, with three of its four paragraphs about the AGENT rather than
-about their system: notes from a previous session, a generator that had been deleted and rebuilt, a
-regression stripped by hand. Two of those notes were also out of date, which is worse than verbose: it
-warned somebody about defects that no longer existed (dono, 06/08).
-
-The pull to report your own work at the end of a long job beats a rule written sixty lines earlier. So
-the rule became a program. What you have in hand when the run ends - your notes, your retries, your
-repairs - has no way into a block that a command prints.
-
-**Anything you think belongs on that screen and is not in the command's output does not belong on that
-screen.** If it is a real finding, it is already in the report or in the causes screen; if it is about
-what you did, it is not theirs.
-
-## 7. THE OFFER
-
-There is exactly one thing to offer, and it is not the fix: it is the two lines that wire the system
-up. Until a stylesheet imports the tokens and an element carries \`data-ds\`, none of the tokens reach
-the browser.
-
-\`summary\` already prints both. Say nothing more about them.
-
-**Never offer \`doctor --fix\` here.** It was offered for a while, with the number of values that have a
-token - and on an unwired project that swap points hundreds of literals at variables the browser
-cannot resolve, so the declarations are dropped and the page changes (dono, 06/08: 210 values, in a
-project where neither line was in place). The doctor itself now refuses in that state, and it is the
-right place for the offer: it can see the wiring, and this run cannot see what they do after it ends.
-
----
-
-## 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. The last
-  screen is \`summary\`'s output and nothing else - see section 6 for why that stopped being a rule and
-  became a command.
-- **Never offers a fix that the wiring blocks.** A swap to tokens that do not reach the browser
-  changes the page, and it would be our command that changed it.
-`;
 export const INIT_SKILL_PATH = ".claude/skills/sui-init/SKILL.md";
+export const INIT_SKILL = '---\nname: sui-init\ndescription: 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\u00e7ar", "importar meu projeto"). Asks everything up front, measures while asking, and ends in four lines.\n---\n\n# The first run - served live\n\nThis playbook is served from the platform, not shipped in this file - it is\nalways current, and your context only carries the step you are on.\n\n1. Call the `playbook` tool on the `synthesisui` MCP server with\n   { "skill": "init" } - you get the framing and a table of contents.\n2. Fetch ONLY the chapter for the step you are on:\n   { "skill": "init", "section": "<id from the toc>" }. Never fetch more\n   than the current step needs.\n3. Follow it exactly. When the step is done, fetch the next chapter.\n\nIf the tool answers that you are not signed in, run `npx synthesisui login`\nin the terminal and call it again. If the `synthesisui` MCP server is not\navailable at all, run `npx synthesisui connect`, restart the session, and\ninvoke this skill again.\n';

package/package.json

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