@sableui/react 0.17.0 → 0.19.0

package/bin/sable.mjs

@@ -36,13 +36,15 @@
 
 import { spawnSync } from "node:child_process"
 import { appendFileSync, existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { createRequire } from "node:module"
 import { dirname, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { skeletonize } from "../scripts/skeleton.mjs"
 import { claudeStopHook, installAgentSkill, installClaudeStopHook } from "../scripts/agent-setup.mjs"
+import { adoptionReport, swapLines } from "../scripts/adoption.mjs"
 import { patchChecks } from "../scripts/patches.mjs"
 import { sourcesCheck } from "../scripts/sources.mjs"
-import { detectFramework, detectPackageManager, fixWiring, fontsCheck, providerSnippet, tailwindBuildCheck } from "../scripts/wiring.mjs"
+import { detectFramework, detectPackageManager, fixWiring, fontsCheck, installCommand, providerSnippet, tailwindBuildCheck } from "../scripts/wiring.mjs"
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = join(HERE, "..")
@@ -119,7 +121,7 @@ const COMMANDS = [
 	},
 	{
 		name: "setup",
-		summary: "Install package-backed skill entry files for coding agents, preserving local edits.",
+		summary: "Install package-backed skill entry files for coding agents, plus a short managed block in AGENTS.md / CLAUDE.md that sends every UI request through the skill, preserving local edits.",
 		arg: null,
 		flags: [
 			{ name: "--agent", value: null, describe: "Install skill entry files. Required." },
@@ -128,6 +130,7 @@ const COMMANDS = [
 			{ name: "--update", value: null, describe: "Refresh unchanged managed entries after a package upgrade." },
 			{ name: "--dry-run", value: null, describe: "Check and report the destination without writing files." },
 			{ name: "--hook", value: null, describe: "Also add a Claude Code Stop hook that runs `sable check` to .claude/settings.json (Claude targets only). Without it, setup prints the hook and writes nothing there." },
+			{ name: "--no-instructions", value: null, describe: "Skip the managed Sable block in AGENTS.md / CLAUDE.md. Without that block an agent uses the skill only when a request names it." },
 		],
 		returns: ["setup.agent"],
 	},
@@ -220,6 +223,13 @@ const COMMANDS = [
 		],
 		returns: ["provider.list", "provider.detail", "provider.props", "provider.examples"],
 	},
+	{
+		name: "icon",
+		summary: "The icon names <Icon name> renders with the bundled set. Check a name before using it: an unknown one renders nothing.",
+		arg: { name: "name", required: false },
+		flags: [],
+		returns: ["icon.list", "icon.detail"],
+	},
 	{
 		name: "token",
 		summary: "The token contract, with intent — what each token means and what it is NOT.",
@@ -249,7 +259,7 @@ const COMMANDS = [
 	},
 	{
 		name: "doctor",
-		summary: "Check this project's Sable wiring. Exits 1 on any failure.",
+		summary: "Check this project's Sable wiring, and warn when its UI barely uses Sable (adoption). Exits 1 on any wiring failure.",
 		arg: null,
 		flags: [
 			{ name: "--fix", value: null, describe: "Apply the fixes that need no judgment (imports in order, @source, missing packages, Vite dedupe and Tailwind plugin, fonts, IconProvider in a starter entry), print the rest, then check again." },
@@ -265,10 +275,26 @@ const COMMANDS = [
 		flags: [
 			{ name: "--dry-run", value: null, describe: "Report every change without writing or installing anything." },
 			{ name: "--no-agent", value: null, describe: "Skip the agent skill (sable setup --agent)." },
+			{ name: "--no-instructions", value: null, describe: "Install the skill but skip its managed block in AGENTS.md / CLAUDE.md." },
+			{ name: "--hook", value: null, describe: "Also add the Claude Code Stop hook that runs `sable check` before a task can end. In a terminal, init asks; elsewhere it only prints the hook." },
+			{ name: "--no-hook", value: null, describe: "Don't ask about the Stop hook." },
 			{ name: "--no-install", value: null, describe: "Print install commands instead of running them." },
 		],
 		returns: ["init"],
 	},
+	{
+		name: "upgrade",
+		summary: "Update @sableui/react to the latest release, then run the new version's init: skill entries and the AGENTS.md / CLAUDE.md block refreshed, wiring checked, adoption reported. Safe on an app that is already set up.",
+		arg: null,
+		flags: [
+			{ name: "--dry-run", value: null, describe: "Print the update command and preview init's changes without installing or writing anything." },
+			{ name: "--no-install", value: null, describe: "Skip the package update (you updated it yourself); just run the installed version's init." },
+			{ name: "--hook", value: null, describe: "Passed to init: add the Claude Code Stop hook." },
+			{ name: "--no-hook", value: null, describe: "Passed to init: don't ask about the Stop hook." },
+			{ name: "--no-instructions", value: null, describe: "Passed to init: skip the AGENTS.md / CLAUDE.md block." },
+		],
+		returns: ["init"],
+	},
 	{
 		name: "grade",
 		summary: "Static contract checks and evidence review. Original compositions carry no penalty; no automatic taste score.",
@@ -358,6 +384,7 @@ const ERROR_CODES = [
 	{ code: "ERR_PRESET_CONTRAST", when: "A label on a brand or status fill (primary, sidebar-primary, highlight, destructive, success, tone-warning, tone-info) misses 4.5:1 or APCA Lc 60. Apply the suggested pair, or record an `exceptions` entry with a reason." },
 	{ code: "ERR_AGENT_SETUP", when: "The packaged skill is missing, the destination is linked, or existing local edits would be overwritten." },
 	{ code: "ERR_INIT", when: "sable init ran outside an app root (no package.json)." },
+	{ code: "ERR_UPGRADE", when: "sable upgrade ran where @sableui/react is not a dependency, or the package manager's update failed." },
 	{ code: "ERR_UNKNOWN_COMMAND", when: "The first argument is not a command." },
 	{ code: "ERR_MISSING_ARGUMENT", when: "A command that requires an argument got none." },
 	{ code: "ERR_UNKNOWN_COMPONENT", when: "No component by that name. `suggestions` carries near matches." },
@@ -368,6 +395,7 @@ const ERROR_CODES = [
 	{ code: "ERR_UNKNOWN_UTILITY", when: "No utility or variant by that name. `suggestions` carries near matches." },
 	{ code: "ERR_UNKNOWN_DOC", when: "No package guide or doc mirror by that slug. `suggestions` carries near matches and the package guides." },
 	{ code: "ERR_UNKNOWN_PROVIDER", when: "No provider by that name. `suggestions` carries near matches." },
+	{ code: "ERR_UNKNOWN_ICON", when: "No icon by that name in the contract. `suggestions` carries the names to use instead." },
 	{ code: "ERR_UNKNOWN_EXAMPLE", when: "The component has no example with that label. `suggestions` carries near matches as commands." },
 	{ code: "ERR_LINT_INPUT", when: "sable lint --json: a path to lint does not exist." },
 	{ code: "ERR_CHECK_FAILED", when: "sable check: doctor, lint, or grade failed. `data.checks` names which." },
@@ -551,14 +579,32 @@ const importLine = (name) => `import { ${name} } from "@sableui/react"`
 const PROVIDERS = R.providers?.items ?? []
 const findProvider = (name) => PROVIDERS.find((p) => p.name.toLowerCase() === String(name).toLowerCase())
 
+/**
+ * Exported parts by name → the entry that documents them. `PropertyRow`,
+ * `WorkspaceBar`, `CollapsibleIndicator` and `Panel` are real exports with no
+ * entry of their own, and `sable component PropertyRow` used to answer
+ * ERR_UNKNOWN_COMPONENT — so an agent that knew the right name concluded the
+ * part did not exist and built its own. A part shared by two entries (a
+ * MenuRadioGroup under Menu and SettingsMenu) resolves to the first.
+ */
+const PARTS = new Map()
+for (const c of COMPONENTS)
+	for (const s of c.subcomponents ?? []) {
+		const sub = typeof s === "string" ? { name: s.split(/\s+[—-]\s+/)[0].trim(), description: s } : s
+		if (sub.name && !PARTS.has(sub.name.toLowerCase())) PARTS.set(sub.name.toLowerCase(), { parent: c, part: sub })
+	}
+const findPart = (name) => PARTS.get(String(name).toLowerCase())
+
 function findComponent(name) {
 	const hit = COMPONENTS.find((c) => c.name.toLowerCase() === name.toLowerCase())
 	if (hit) return hit
+	const part = findPart(name)
+	if (part) return { ...part.parent, partOf: part.parent.name, part: part.part }
 	fail(
 		"ERR_UNKNOWN_COMPONENT",
 		`No component named "${name}".`,
 		[
-			...nearest(name, [...COMPONENTS, ...PROVIDERS].map((c) => c.name)).map((n) => `Did you mean ${n}?`),
+			...nearest(name, [...COMPONENTS, ...PROVIDERS].map((c) => c.name).concat([...PARTS.values()].map((p) => p.part.name))).map((n) => `Did you mean ${n}?`),
 			`sable search "${name}" — searches summaries and keywords too`,
 			"sable component --list",
 		],
@@ -629,14 +675,23 @@ function cmdSearch() {
 
 	const pool = []
 	if (!type || type === "component")
-		for (const c of COMPONENTS)
+		for (const c of COMPONENTS) {
 			pool.push({ kind: "component", name: c.name, summary: c.summary, status: c.status, group: c.group, ...(c.composition ? { reference: true, parts: c.composition } : {}), _s: score({ name: c.name, keywords: c.keywords, text: `${c.summary} ${c.usage?.description ?? ""}` }) })
+			// Parts are found by their own name and description: `WorkspaceBar` and
+			// `PropertyRow` are what a need is called, and they used to match nothing
+			// (or rank ColorField first, for a word in its prose). A part's hit names
+			// its entry, which is where its contract lives.
+			for (const s of c.subcomponents ?? []) {
+				if (typeof s !== "object" || !s.name || PARTS.get(s.name.toLowerCase())?.parent !== c) continue
+				pool.push({ kind: "component", name: s.name, partOf: c.name, summary: `${s.description ?? ""} Part of ${c.name}.`.trim(), status: c.status, group: c.group, _s: score({ name: s.name, text: s.description ?? "" }) })
+			}
+		}
 	if (!type || type === "provider")
 		for (const p of PROVIDERS)
 			pool.push({ kind: "provider", name: p.name, summary: p.summary, _s: score({ name: p.name, keywords: ["provider", ...(p.companions ?? [])], text: `${p.summary} ${p.placement ?? ""}` }) })
 	if (!type || type === "pattern")
 		for (const p of PATTERNS)
-			pool.push({ kind: "pattern", name: p.name, summary: p.summary, _s: score({ name: p.name, text: `${p.summary} ${p.intent ?? ""}` }) })
+			pool.push({ kind: "pattern", name: p.name, summary: p.summary, _s: score({ name: p.name, keywords: p.keywords, text: `${p.summary} ${p.intent ?? ""}` }) })
 	if (!type || type === "block")
 		for (const b of BLOCKS)
 			pool.push({ kind: "block", name: b.name, summary: b.summary, family: b.family, _s: score({ name: b.name, keywords: [b.family.toLowerCase()], text: `${b.summary} ${b.intent ?? ""}` }) })
@@ -696,7 +751,9 @@ function cmdSearch() {
 		retrieve:
 			h.kind === "example"
 				? `sable component ${h.component} --example "${h.label.replace(/"/g, '\\"')}"`
-				: `sable ${h.kind === "doc" ? "docs" : h.kind} ${h.name}`,
+				: h.partOf
+					? `sable component ${h.partOf} --props`
+					: `sable ${h.kind === "doc" ? "docs" : h.kind} ${h.name}`,
 	}))
 	const anyReference = results.some((h) => h.reference)
 	ok("search", { query, count: results.length, results }, () =>
@@ -704,7 +761,7 @@ function cmdSearch() {
 			...results.map((h) =>
 				DENSE
 					? `${h.kind}/${h.name}${h.reference ? " (reference)" : ""}`
-					: `${h.kind.padEnd(9)} ${`${h.name}${h.reference ? " ◇" : ""}`.padEnd(24)} ${firstSentence(h.summary ?? "")}`,
+					: `${h.kind.padEnd(9)} ${`${h.name}${h.reference ? " ◇" : ""}`.padEnd(24)} ${h.partOf ? `(part of ${h.partOf}) ` : ""}${firstSentence(h.summary ?? "")}`,
 			),
 			...(anyReference && !DENSE
 				? ["", "◇ a reference layout: use it when it fits the brief, or compose your own from Sable's parts. Either is fine. Behaviour components (controls, overlays, fields) are always used, never rebuilt."]
@@ -781,6 +838,36 @@ function firstSentence(s) {
 	return text
 }
 
+/* ── icon ───────────────────────────────────────────────────────────────────── */
+
+/**
+ * The names `<Icon name>` draws, and the other sets' names it accepts for them
+ * (registry → iconContract, generated from src/icon/names.ts). A work tracker
+ * asked for nine names that did not exist, got blank space, and wrote its own
+ * alias map, because nothing listed the names that do.
+ */
+function cmdIcon() {
+	const names = R.iconContract?.names ?? []
+	const aliases = R.iconContract?.aliases ?? {}
+	const set = new Set(names)
+	const name = rest[0]
+	if (!name)
+		return ok("icon.list", { count: names.length, names, aliases, note: R.iconContract?.note }, () =>
+			[`${names.length} icon names (the bundled Reicon set). An app adds more with composeIconSets and lists them in .sable/icons.json.`, "", names.join("  ")].join("\n"),
+		)
+	if (set.has(name)) return ok("icon.detail", { name, known: true, usage: `<Icon name="${name}" />` }, () => `${name} — in the contract.\n<Icon name="${name}" />`)
+	if (aliases[name])
+		return ok("icon.detail", { name, known: false, alias: aliases[name], usage: `<Icon name="${aliases[name]}" />` }, () =>
+			`${name} is another set's name for ${aliases[name]}: <Icon> draws it, but write the contract name.\n<Icon name="${aliases[name]}" />`,
+		)
+	const use = nearest(name, names)
+	fail("ERR_UNKNOWN_ICON", `No icon named "${name}"; <Icon name="${name}"> renders nothing.`, [
+		...use.map((n) => `Use "${n}"`),
+		"Or add the glyph to the app's set with composeIconSets and list it in .sable/icons.json",
+		"sable icon — every name",
+	])
+}
+
 /* ── component ──────────────────────────────────────────────────────────────── */
 
 function cmdComponent() {
@@ -813,12 +900,16 @@ function cmdComponent() {
 	// A provider is asked for the way a component is. Answer with its entry rather
 	// than ERR_UNKNOWN_COMPONENT, which is what `sable component SableThemeProvider`
 	// used to say.
-	if (!COMPONENTS.some((c) => c.name.toLowerCase() === rest[0].toLowerCase()) && findProvider(rest[0])) return cmdProvider()
+	if (!COMPONENTS.some((c) => c.name.toLowerCase() === rest[0].toLowerCase()) && !findPart(rest[0]) && findProvider(rest[0])) return cmdProvider()
 	const c = findComponent(rest[0])
+	// Asked for a part: answer with its entry, and say so first, so the agent
+	// knows the part exists, what to import, and where the rest of it is documented.
+	const part = c.partOf ? { name: c.part.name, partOf: c.partOf, import: `import { ${c.partOf}, ${c.part.name} } from "@sableui/react"`, ...(c.part.type ? { type: c.part.type } : {}), description: c.part.description ?? "" } : null
+	const partLine = part ? `${part.name} is part of ${part.partOf}.${part.description ? ` ${part.description}` : ""}\n${part.import}\n` : ""
 
 	if (flags.has("props"))
-		return ok("component.props", { name: c.name, props: c.props ?? [], subcomponents: c.subcomponents ?? [] }, () =>
-			renderProps(c),
+		return ok("component.props", { name: c.name, ...(part ? { part } : {}), props: c.props ?? [], subcomponents: c.subcomponents ?? [] }, () =>
+			`${partLine}${part ? "\n" : ""}${renderProps(c)}`,
 		)
 	if (flags.has("examples"))
 		return ok("component.examples", { name: c.name, examples: c.examples ?? [] }, () => renderExamples(c))
@@ -849,6 +940,7 @@ function cmdComponent() {
 		import: importLine(c.name),
 		summary: c.summary,
 		...(c.composition ? { composition: c.composition } : {}),
+		...(part ? { part } : {}),
 	}
 	if (level !== "brief") {
 		data.props = c.props ?? []
@@ -866,6 +958,7 @@ function cmdComponent() {
 
 	ok("component.detail", data, () =>
 		[
+			partLine,
 			`${c.name}  [${c.status}]  ${c.group}  register:${c.register}`,
 			c.summary,
 			c.composition
@@ -1471,6 +1564,21 @@ function doctorReport() {
 			)
 	}
 
+	/* Adoption: wiring that holds says nothing about whether the app composes
+	 * Sable. An agent that never loaded the skill wires the stylesheet, uses the
+	 * tokens, and writes its own Button and Modal. A warning, never a failure:
+	 * check lists the swaps, and moving working screens is the user's call. */
+	if (pkg && { ...pkg.dependencies, ...pkg.devDependencies }["@sableui/react"]) {
+		const files = src
+			.filter((f) => /\.(tsx|jsx)$/.test(f.path) && !/\.(test|spec|stories)\./.test(f.path))
+			.map((f) => ({ rel: relative(CWD, f.path).replaceAll("\\", "/"), text: f.text }))
+		const adoption = adoptionReport({ files, components: COMPONENTS, deps: { ...pkg.dependencies, ...pkg.devDependencies } })
+		if (adoption.level === "none" || adoption.level === "low")
+			add("warn", "adoption", `${adoption.summary} ${adoption.recommendation}`, "sable check src lists each swap; then ask your agent to /sable audit (or $sable audit) the app's use of Sable.")
+		else if (adoption.level === "sable") add("pass", "adoption", adoption.summary)
+		else if (adoption.level === "fresh") add("info", "adoption", adoption.summary)
+	}
+
 	/* Tailwind in the build, and the theme's fonts: both fail as a page that
 	 * renders, just not as Sable — unstyled, or in system fonts. */
 	if (pkg) {
@@ -1567,7 +1675,7 @@ function cmdDoctorFix() {
  * app still has to mount. Each step is the code its own command runs, so init
  * can never wire an app differently from what doctor checks.
  */
-function cmdInit() {
+async function cmdInit() {
 	if (!existsSync(join(CWD, "package.json")))
 		fail("ERR_INIT", `No package.json in ${CWD}.`, ["Run sable init from your app's root.", "Starting fresh: pnpm create vite@latest my-app --template react-ts, then pnpm add @sableui/react && pnpm exec sable init"])
 	const dryRun = flags.has("dry-run")
@@ -1582,26 +1690,57 @@ function cmdInit() {
 		try {
 			// update: an unchanged managed entry from an older Sable is refreshed;
 			// one with local edits still refuses, and is reported for the user.
-			const setup = installAgentSkill({ root: CWD, project: CWD, packageRoot: PKG_ROOT, target: "all", update: true, dryRun })
-			agent = { status: dryRun ? "would-apply" : "applied", destinations: setup.destinations, next: setup.next }
+			const setup = installAgentSkill({ root: CWD, project: CWD, packageRoot: PKG_ROOT, target: "all", update: true, dryRun, instructions: !flags.has("no-instructions") })
+			agent = { status: dryRun ? "would-apply" : "applied", destinations: setup.destinations, instructions: setup.instructions, instructionsChanged: setup.instructionsChanged, next: setup.next }
 		} catch (error) {
 			agent = { status: "manual", detail: error.message, fix: "sable setup --agent --dry-run" }
 		}
 
+	/* The Stop hook changes how Claude Code behaves, so init never adds it on its
+	 * own. A person at a terminal is asked; an agent running init (no TTY) gets
+	 * the one-line offer in the output, and --hook adds it either way. */
+	let hook = null
+	if (agent.status === "applied" || agent.status === "would-apply") {
+		let want = flags.has("hook")
+		const interactive = process.stdin.isTTY && process.stdout.isTTY && !JSON_OUT && !dryRun
+		if (!want && !flags.has("no-hook") && interactive) {
+			const { createInterface } = await import("node:readline/promises")
+			const rl = createInterface({ input: process.stdin, output: process.stdout })
+			const answer = await rl.question("Add a Claude Code Stop hook, so Claude can't end a task while `sable check` fails? [Y/n] ")
+			rl.close()
+			want = !/^\s*n/i.test(answer)
+		}
+		try {
+			hook = want ? installClaudeStopHook({ root: CWD, project: CWD, dryRun }) : claudeStopHook({ root: CWD, project: CWD })
+		} catch (error) {
+			hook = { installed: false, error: error.message }
+		}
+	}
+
 	const after = dryRun ? before : doctorReport()
 	verifyFixes(fixes, after)
 	const mounted = after.checks.find((c) => c.name === "icons")?.status === "pass"
 	const providers = { ...providerSnippet(framework), mounted }
-	const data = { framework: { id: framework.id, label: framework.label }, packageManager, dryRun, fixes, agent, providers, doctor: after }
+	// An app that is wired but built mostly without Sable needs the audit path
+	// next, not a new build: `build` would start the product over.
+	const lowAdoption = after.checks.some((c) => c.name === "adoption" && c.status === "warn")
+	const data = { framework: { id: framework.id, label: framework.label }, packageManager, dryRun, fixes, agent, stopHook: hook, providers, doctor: after, next: lowAdoption ? EXISTING_APP_NEXT : (agent.next ?? null) }
 
 	if (JSON_OUT) process.stdout.write(`${JSON.stringify({ type: "init", data }, null, DENSE ? 0 : 1)}\n`)
 	else {
 		const agentText = {
-			applied: () => `Agent skill: installed at ${agent.destinations.join(", ")}.`,
-			"would-apply": () => `Agent skill: would install at ${agent.destinations.join(", ")}.`,
+			applied: () => `Agent skill: installed at ${agent.destinations.join(", ")}.\n${instructionsText({ ...agent, dryRun })}`,
+			"would-apply": () => `Agent skill: would install at ${agent.destinations.join(", ")}.\n${instructionsText({ ...agent, dryRun })}`,
 			skipped: () => "Agent skill: skipped (--no-agent).",
 			manual: () => `Agent skill: not installed — ${agent.detail}\n  → ${agent.fix}`,
 		}[agent.status]()
+		const hookText = !hook
+			? ""
+			: hook.error
+				? `Stop hook: not added — ${hook.error}`
+				: hook.installed
+					? `Stop hook: ${dryRun ? "would add to" : hook.alreadyPresent ? "already in" : "added to"} ${hook.settingsFile}. Claude can't end a task while sable check fails.`
+					: `Stop hook (optional): sable init --hook, or sable setup --agent --hook, makes Claude Code run sable check before it can end a task.`
 		const iconsFix = fixes.find((f) => f.check === "icons")
 		const providerText = mounted
 			? "Providers: <IconProvider> is mounted. MotionProvider and SableThemeProvider are optional: sable provider --list."
@@ -1617,13 +1756,14 @@ function cmdInit() {
 				"",
 				fixes.length ? `${dryRun ? "Would fix:" : "Fixes:"}\n${fixLines(fixes)}` : "Nothing to fix.\n",
 				agentText,
+				...(hookText ? [hookText] : []),
 				"",
 				providerText,
 				"",
 				`Doctor:\n${doctorLines(after.checks)}`,
 				after.failed
 					? `[sable init] ✗ ${after.failed} failure(s) ${dryRun ? "now" : "left; the steps marked ! need you"}. Re-check with sable doctor.`
-					: `[sable init] ✓ wiring holds. Next: ${agent.next ?? "sable docs building-with-sable"}`,
+					: `[sable init] ✓ wiring holds. Next: ${lowAdoption ? EXISTING_APP_NEXT : (agent.next ?? "sable docs building-with-sable")}`,
 				"",
 			].join("\n"),
 		)
@@ -1632,6 +1772,54 @@ function cmdInit() {
 	process.exit(after.failed ? 1 : 0)
 }
 
+const EXISTING_APP_NEXT = "most of this app's UI isn't built from Sable yet. Tell your agent \"move this app onto Sable\": it lists what to swap and asks before changing anything."
+
+/* ── upgrade ────────────────────────────────────────────────────────────────── */
+
+/**
+ * The whole update in one command: the package, then the NEW version's init.
+ * This process is the old CLI, so after installing it hands over to the
+ * freshly installed bin rather than running its own init: the skill entries,
+ * the instructions block and the checks must be the new release's.
+ */
+function cmdUpgrade() {
+	let pkg
+	try {
+		pkg = JSON.parse(readFileSync(join(CWD, "package.json"), "utf8"))
+	} catch {
+		fail("ERR_UPGRADE", `No package.json in ${CWD}.`, ["Run sable upgrade from your app's root."])
+	}
+	const spec = pkg.dependencies?.["@sableui/react"] ?? pkg.devDependencies?.["@sableui/react"]
+	if (!spec) fail("ERR_UPGRADE", "@sableui/react is not a dependency of this project.", ["pnpm add @sableui/react, then pnpm exec sable init"])
+	const pm = detectPackageManager(CWD)
+	const dryRun = flags.has("dry-run")
+	// A tarball, link or workspace copy is not something "latest" can replace.
+	const local = /^(?:file:|link:|workspace:|portal:|\.{0,2}\/)/.test(String(spec))
+	const install = installCommand(pm, ["@sableui/react@latest"], { dev: !pkg.dependencies?.["@sableui/react"] })
+	const say = (line) => { if (!JSON_OUT) process.stdout.write(`${line}\n`) }
+
+	if (flags.has("no-install")) say("sable upgrade — skipping the package update (--no-install).")
+	else if (local) say(`sable upgrade — @sableui/react comes from ${spec}, which "latest" can't replace. Update that copy yourself; running the installed version's init.`)
+	else if (dryRun) say(`sable upgrade — would run: ${install.join(" ")}`)
+	else {
+		say(`sable upgrade — ${install.join(" ")}`)
+		const r = spawnSync(install[0], install.slice(1), { cwd: CWD, stdio: JSON_OUT ? "pipe" : "inherit", shell: process.platform === "win32" })
+		if (r.status !== 0) fail("ERR_UPGRADE", `${install.join(" ")} exited ${r.status}.`, ["Fix the install, then run sable upgrade --no-install."])
+	}
+
+	// The installed package's own CLI, resolved the way the skill resolves it.
+	let bin = join(PKG_ROOT, "bin", "sable.mjs")
+	try {
+		const registry = createRequire(join(CWD, "package.json")).resolve("@sableui/react/registry.json")
+		const installed = join(dirname(registry), "bin", "sable.mjs")
+		if (existsSync(installed)) bin = installed
+	} catch { /* not resolvable from here (a workspace copy): this CLI's init is the installed one */ }
+	const passed = ["dry-run", "hook", "no-hook", "no-instructions", "json"].filter((f) => flags.has(f)).map((f) => `--${f}`)
+	const r = spawnSync(process.execPath, [bin, "init", ...passed], { cwd: CWD, stdio: "inherit" })
+	logInvocation(r.status ?? 1)
+	process.exit(r.status ?? 1)
+}
+
 function doctorLines(checks, indent = "  ") {
 	const mark = { pass: "✓", warn: "!", fail: "✗", info: "·" }
 	return checks
@@ -1719,7 +1907,7 @@ const MANUAL_REVIEW = [
 	{ step: "Walk the journey", how: "sable docs reviewing-a-journey — operate the primary task and its recovery path end to end; loading, empty, error and success states; keyboard and touch." },
 	{ step: "Review the motion", how: "sable docs reviewing-motion — observe playback and interruption for anything that moves." },
 	{ step: "Check reduced motion", how: "Turn on prefers-reduced-motion (or MotionProvider \"reduced\"): state still changes, nothing essential depends on animation, nothing keeps moving." },
-	{ step: "Write the reuse inventory", how: "List the Sable components, parts, utilities and token groups used, and every app-owned UI or CSS addition with the catalog search that justified it. Start from the app-owned surfaces sable check lists (sable grade --json → inventory) and note, for each, whether you used the Sable part named beside it or kept your own. Either is fine for layout and look. Behaviour (controls, overlays, keyboard handling) comes from Sable." },
+	{ step: "Write the reuse inventory", how: "List the Sable components, parts, utilities and token groups used, and every app-owned UI or CSS addition with the catalog search that justified it. Start from the app-owned surfaces and rebuilt parts sable check lists (sable grade --json → inventory, rebuiltParts) and note, for each, whether you used the Sable part named beside it or kept your own, and why. Either is fine for layout and look. Behaviour (controls, overlays, keyboard handling) comes from Sable." },
 	{ step: "Record what you learned", how: "sable docs learning-from-builds — keep conditional lessons with evidence (sable learn --record); never record human approval you did not get." },
 ]
 
@@ -1751,7 +1939,8 @@ function cmdCheck() {
 		details: doctorFailures.map((c) => `${c.name}: ${c.detail}${c.fix ? ` → ${c.fix}` : ""}`),
 		// Warnings and notes don't fail the check, but they are things to act on,
 		// and a passing check that printed nothing else hid them from the agent.
-		notes: doctor.checks.filter((c) => c.status === "warn" || c.status === "info").map((c) => `${c.name}: ${c.detail}${c.fix ? ` → ${c.fix}` : ""}`),
+		// Adoption is reported once, from grade, with its swaps.
+		notes: doctor.checks.filter((c) => (c.status === "warn" || c.status === "info") && c.name !== "adoption").map((c) => `${c.name}: ${c.detail}${c.fix ? ` → ${c.fix}` : ""}`),
 		data: doctor,
 	})
 
@@ -1788,7 +1977,7 @@ function cmdCheck() {
 		const LABELS = { hallucinatedComponent: "hallucinated components", hallucinatedProp: "hallucinated props", radixIdiom: "Radix idioms", hardcodedControl: "hardcoded control heights", offContractIcon: "off-contract icons" }
 		const found = Object.entries(LABELS).filter(([k]) => grade.counts[k])
 		const reviewMissing = review.length > 0 && grade.review?.status !== "review-recorded"
-		const details = found.flatMap(([k]) => grade.findings[k].map((f) => `${LABELS[k]} — ${f.file}:${f.line} → ${f.name ?? f.prop ?? f.what ?? f.match}${f.component ? ` on ${f.component}` : ""}${f.from ? ` from ${f.from}${f.reason ? ` (${f.reason})` : ""}` : ""}`))
+		const details = found.flatMap(([k]) => grade.findings[k].map((f) => `${LABELS[k]} — ${f.file}:${f.line} → ${f.name ?? f.prop ?? f.what ?? f.match}${f.component ? ` on ${f.component}` : ""}${f.from ? ` from ${f.from}${f.reason ? ` (${f.reason})` : ""}` : ""}${f.via ? ` via ${f.via}` : ""}${f.suggest?.length ? `; the set has ${f.suggest.join(", ")} (sable icon)` : ""}`))
 		if (reviewMissing) details.push(`review: ${grade.review?.status ?? "missing"}${grade.review?.problems?.length ? ` — ${grade.review.problems.join("; ")}` : ""}`)
 		checks.push({
 			name: "grade",
@@ -1801,20 +1990,35 @@ function cmdCheck() {
 				.filter(Boolean)
 				.join("; "),
 			details,
-			data: { score: grade.score, contract: grade.contract, counts: grade.counts, review: grade.review, findings: grade.findings },
+			// A half-themed palette passes the contract and breaks the moment
+			// someone switches modes, so it is said on the grade line, as a warning.
+			notes: [
+				...(grade.modes?.status === "warn" ? [`warn — colour modes: ${grade.modes.lightOnly.length} colour token(s) set for light with no dark value (${grade.modes.lightOnly.slice(0, 4).map((t) => `--${t.name}`).join(", ")}${grade.modes.lightOnly.length > 4 ? ", …" : ""}) → ${grade.modes.fix}`] : []),
+				...(grade.modes && !grade.modes.modeControl ? ["colour modes: nothing imports ThemeSwitcher, ThemeSelector or useSableTheme, so no one can switch modes to review both → mount ThemeSwitcher under SableThemeProvider, or pin the one mode the brief asks for"] : []),
+			],
+			data: { score: grade.score, contract: grade.contract, counts: grade.counts, review: grade.review, findings: grade.findings, modes: grade.modes },
 		})
 	}
 	/* App-owned surfaces, from grade. Never a failure: the input to the reuse
 	 * inventory (finish step 6), which otherwise gets written from memory. */
 	const inventory = grade && grade.type !== "error" ? (grade.inventory ?? null) : null
+	/* Adoption, from grade. Never a failure either: wiring can hold while the app
+	 * composes almost none of Sable, and the move onto it is the user's call. */
+	const adoption = grade && grade.type !== "error" ? (grade.adoption ?? null) : null
+	/* Rebuilt parts, from grade: elements and app CSS standing in for a part
+	 * Sable ships, or reaching into one. Notes, answered in the reuse inventory. */
+	const rebuilt = grade && grade.type !== "error" ? (grade.rebuiltParts ?? null) : null
+	const lowAdoption = adoption && (adoption.level === "none" || adoption.level === "low")
 
 	const failed = checks.filter((c) => c.status !== "pass").map((c) => c.name)
 	// A build that still scans all of Sable ships every component's classes;
 	// trimming it is a finish step, because sources are only final once the app is.
-	const manual = doctor.checks.some((c) => c.name === "css:size")
-		? [...MANUAL_REVIEW, { step: "Ship only the CSS you use", how: "sable sources --write src/sable-sources.css, then @import it in place of the whole-package @source (about 32 KB of CSS gzipped down to what the app imports). Re-run it whenever you import something new from Sable; sable check fails while it is stale." }]
-		: MANUAL_REVIEW
-	const data = { paths, passed: !failed.length, failed, checks, inventory, manualReview: manual }
+	const manual = [
+		...(lowAdoption ? [{ step: "Ask about moving onto Sable", how: `${adoption.recommendation} The swaps are listed under Adoption above; sable docs auditing-an-app ("Adoption") covers how to put the choice to the user.` }] : []),
+		...MANUAL_REVIEW,
+		...(doctor.checks.some((c) => c.name === "css:size") ? [{ step: "Ship only the CSS you use", how: "sable sources --write src/sable-sources.css, then @import it in place of the whole-package @source (about 32 KB of CSS gzipped down to what the app imports). Re-run it whenever you import something new from Sable; sable check fails while it is stale." }] : []),
+	]
+	const data = { paths, passed: !failed.length, failed, checks, inventory, adoption, rebuiltParts: rebuilt, manualReview: manual }
 	const MARK = { pass: "✓", fail: "✗", error: "✗" }
 	const MAX_DETAILS = 12
 	const summaryText = () =>
@@ -1824,7 +2028,7 @@ function cmdCheck() {
 				`  ${MARK[c.status]} ${c.name.padEnd(7)}${c.summary}`,
 				...c.details.slice(0, MAX_DETAILS).map((d) => `      ${d}`),
 				...(c.details.length > MAX_DETAILS ? [`      … ${c.details.length - MAX_DETAILS} more: sable ${c.name}${c.name === "doctor" ? "" : ` ${paths.join(" ")}`}`] : []),
-				...(c.notes ?? []).map((n) => `      note — ${n}`),
+				...(c.notes ?? []).map((n) => (n.startsWith("warn — ") ? `      ${n}` : `      note — ${n}`)),
 			]),
 			"",
 			failed.length ? `[sable check] ✗ ${failed.join(", ")} failed. Fix these and run sable check again.` : "[sable check] ✓ doctor, lint and grade pass.",
@@ -1840,6 +2044,27 @@ function cmdCheck() {
 			"",
 		].join("\n")
 	}
+	const rebuiltText = () => {
+		const list = rebuilt?.items ?? []
+		if (!list.length) return ""
+		return [
+			"",
+			`Rebuilt parts — ${list.length}. Sable ships these, or the app styles one from outside. Use the part (or its variant or prop), or say in the reuse inventory why yours stays. A part that cannot fit your design is a missing variant to report, not a reason to rebuild it.`,
+			...list.slice(0, MAX_DETAILS).map((r) => `      ${r.file}:${r.line}  ${r.what}${r.count ? ` ×${r.count}` : ""} → ${r.consider}`),
+			...(list.length > MAX_DETAILS ? [`      … ${list.length - MAX_DETAILS} more: sable grade ${paths.join(" ")} --json → rebuiltParts.items`] : []),
+			"",
+		].join("\n")
+	}
+	const adoptionText = () => {
+		if (!adoption || adoption.level === "empty" || (adoption.level === "sable" && !adoption.swaps.length)) return ""
+		return [
+			"",
+			`Adoption — ${adoption.level}. ${adoption.summary}`,
+			`      ${adoption.recommendation}`,
+			...swapLines(adoption, MAX_DETAILS),
+			"",
+		].join("\n")
+	}
 	const manualText = () =>
 		[
 			"",
@@ -1869,7 +2094,7 @@ function cmdCheck() {
 	}
 
 	if (JSON_OUT) process.stdout.write(`${JSON.stringify({ type: "check", data }, null, DENSE ? 0 : 1)}\n`)
-	else process.stdout.write(`${summaryText()}\n${inventoryText()}${manualText()}\n`)
+	else process.stdout.write(`${summaryText()}\n${adoptionText()}${rebuiltText()}${inventoryText()}${manualText()}\n`)
 	logInvocation(failed.length ? 1 : 0, failed.length ? "ERR_CHECK_FAILED" : undefined)
 	process.exit(failed.length ? 1 : 0)
 }
@@ -1899,6 +2124,15 @@ function cmdDesignTool(script) {
 	passThrough(runScript(join(PKG_ROOT, "scripts", script)))
 }
 
+/** What setup did to the project instructions, in one line. */
+function instructionsText(data) {
+	if (!data.instructions.length) return "Project instructions: skipped (--no-instructions). Agents use the skill only when a request names it."
+	const changed = data.instructionsChanged
+	const files = data.instructions.join(", ")
+	if (!changed.length) return `Project instructions: ${files} already carry the Sable block.`
+	return `Project instructions: ${data.dryRun ? "would add" : "added"} the Sable block to ${changed.join(", ")}, so every UI request goes through the skill. Edit outside its markers; --no-instructions skips it.`
+}
+
 function cmdSetup() {
 	if (!flags.has("agent") || rest.length) fail("ERR_BAD_ARGUMENT", "Use sable setup --agent from your project root.", ["sable setup --agent --dry-run"])
 	const root = flags.get("root")
@@ -1908,7 +2142,7 @@ function cmdSetup() {
 	if (flags.has("hook") && !forClaude)
 		fail("ERR_BAD_ARGUMENT", "--hook installs a Claude Code Stop hook; use it with --target claude or all.", ["sable setup --agent --target claude --hook"])
 	try {
-		const options = { root: root ? resolve(CWD, root) : CWD, project: CWD, packageRoot: PKG_ROOT, target, update: flags.has("update"), dryRun: flags.has("dry-run") }
+		const options = { root: root ? resolve(CWD, root) : CWD, project: CWD, packageRoot: PKG_ROOT, target, update: flags.has("update"), dryRun: flags.has("dry-run"), instructions: !flags.has("no-instructions") }
 		// Preflight the settings file too, so a refusal there writes nothing anywhere.
 		if (flags.has("hook")) installClaudeStopHook({ ...options, dryRun: true })
 		const data = installAgentSkill(options)
@@ -1922,7 +2156,7 @@ function cmdSetup() {
 			: hook.installed
 				? `\n${data.dryRun ? "Would add" : hook.alreadyPresent ? "Already present:" : "Added"} a Claude Code Stop hook to ${hook.settingsFile}: Claude cannot end a task while \`sable check\` fails.`
 				: `\nOptional: block Claude Code from ending a task while \`sable check\` fails. Add this to ${hook.settingsFile} (merge into an existing "hooks" key), or rerun with --hook to add it:\n\n${JSON.stringify(hook.settings, null, 2)}\n\nThe hook runs: ${hook.command}`
-		ok("setup.agent", data, `${data.dryRun ? "Would install" : "Installed"} Sable skill entries at ${data.destinations.map((d) => relative(CWD, join(data.root, d)).replaceAll("\\", "/")).join(", ")}.\nNext: ${data.next}${hookText}`)
+		ok("setup.agent", data, `${data.dryRun ? "Would install" : "Installed"} Sable skill entries at ${data.destinations.map((d) => relative(CWD, join(data.root, d)).replaceAll("\\", "/")).join(", ")}.\n${instructionsText(data)}\nNext: ${data.next}${hookText}`)
 	} catch (error) {
 		fail("ERR_AGENT_SETUP", error.message, ["sable setup --agent --dry-run"])
 	}
@@ -1950,6 +2184,7 @@ const HANDLERS = {
 	setup: cmdSetup,
 	check: cmdCheck,
 	provider: cmdProvider,
+	icon: cmdIcon,
 	manifest: cmdManifest,
 	search: cmdSearch,
 	component: cmdComponent,
@@ -1961,6 +2196,7 @@ const HANDLERS = {
 	docs: cmdDocs,
 	doctor: cmdDoctor,
 	init: cmdInit,
+	upgrade: cmdUpgrade,
 	grade: cmdGrade,
 	learn: cmdLearn,
 	atlas: () => cmdDesignTool("design-atlas.mjs"),

package/dist/{_contract-CDa9-NdB.d.ts → _contract-DlklV0Im.d.ts}

@@ -46,7 +46,7 @@ type TypeScaleToken = (typeof TYPE_SCALE_TOKENS)[number];
  * Set them at a theme or region scope, then keep consuming whole `text-*` tiers.
  * Compact controls still follow TYPE_UI_TOKENS for the workspace register.
  */
-declare const TYPE_REFINEMENT_TOKENS: readonly ["type-display-4xl-size", "type-title-lg-size", "type-title-sm-size", "type-body-lg-size", "type-body-lg-weight", "type-body-lg-leading", "type-body-lg-tracking", "type-body-md-size", "type-body-md-weight", "type-body-md-leading", "type-body-md-tracking", "type-body-sm-size", "type-body-sm-weight", "type-body-sm-leading", "type-body-sm-tracking", "type-body-xs-size", "type-body-xs-weight", "type-body-xs-leading", "type-body-xs-tracking", "type-label-lg-size", "type-label-lg-weight", "type-label-lg-leading", "type-label-lg-tracking", "type-label-md-size", "type-label-md-weight", "type-label-md-leading", "type-label-md-tracking", "type-label-sm-size", "type-label-sm-weight", "type-label-sm-leading", "type-label-sm-tracking", "type-label-xs-size", "type-label-xs-weight", "type-label-xs-leading", "type-label-xs-tracking", "type-label-xs-transform", "type-caption-size", "type-caption-weight", "type-caption-leading", "type-caption-tracking", "type-mono-xl-size", "type-mono-xl-weight", "type-mono-xl-leading", "type-mono-xl-tracking", "type-mono-lg-size", "type-mono-lg-weight", "type-mono-lg-leading", "type-mono-lg-tracking", "type-mono-md-size", "type-mono-md-weight", "type-mono-md-leading", "type-mono-md-tracking", "type-mono-caption-size", "type-mono-caption-weight", "type-mono-caption-leading", "type-mono-caption-tracking", "type-mono-sm-size", "type-mono-sm-weight", "type-mono-sm-leading", "type-mono-sm-tracking"];
+declare const TYPE_REFINEMENT_TOKENS: readonly ["type-base", "type-display-4xl-size", "type-title-lg-size", "type-title-sm-size", "type-body-lg-size", "type-body-lg-weight", "type-body-lg-leading", "type-body-lg-tracking", "type-body-md-size", "type-body-md-weight", "type-body-md-leading", "type-body-md-tracking", "type-body-sm-size", "type-body-sm-weight", "type-body-sm-leading", "type-body-sm-tracking", "type-body-xs-size", "type-body-xs-weight", "type-body-xs-leading", "type-body-xs-tracking", "type-label-lg-size", "type-label-lg-weight", "type-label-lg-leading", "type-label-lg-tracking", "type-label-md-size", "type-label-md-weight", "type-label-md-leading", "type-label-md-tracking", "type-label-sm-size", "type-label-sm-weight", "type-label-sm-leading", "type-label-sm-tracking", "type-label-xs-size", "type-label-xs-weight", "type-label-xs-leading", "type-label-xs-tracking", "type-label-xs-transform", "type-caption-size", "type-caption-weight", "type-caption-leading", "type-caption-tracking", "type-mono-xl-size", "type-mono-xl-weight", "type-mono-xl-leading", "type-mono-xl-tracking", "type-mono-lg-size", "type-mono-lg-weight", "type-mono-lg-leading", "type-mono-lg-tracking", "type-mono-md-size", "type-mono-md-weight", "type-mono-md-leading", "type-mono-md-tracking", "type-mono-caption-size", "type-mono-caption-weight", "type-mono-caption-leading", "type-mono-caption-tracking", "type-mono-sm-size", "type-mono-sm-weight", "type-mono-sm-leading", "type-mono-sm-tracking"];
 type TypeRefinementToken = (typeof TYPE_REFINEMENT_TOKENS)[number];
 /**
  * Overline/eyebrow/kicker type tokens (mode-independent). A theme MAY override
@@ -206,7 +206,7 @@ declare const MARK_TOKENS: readonly ["destructive-mark", "success-mark", "tone-w
  * an unrecognised `text-*` class falls into tailwind-merge's COLOUR group and
  * silently evicts the real colour class, which is a genuinely hard bug to see.
  */
-declare const TYPE_UI_TOKENS: readonly ["type-ui-md-size", "type-ui-md-weight", "type-ui-sm-size", "type-ui-sm-weight", "type-ui-leading", "type-ui-section-weight", "type-ui-micro-size", "type-ui-micro-weight"];
+declare const TYPE_UI_TOKENS: readonly ["type-ui-md-size", "type-ui-md-weight", "type-ui-sm-size", "type-ui-sm-weight", "type-ui-leading", "type-ui-section-weight", "type-ui-micro-size", "type-ui-micro-weight", "type-ui-title-size", "type-ui-title-weight", "type-ui-title-leading"];
 type TypeUiToken = (typeof TYPE_UI_TOKENS)[number];
 type ThemeMode = "light" | "dark";
 /** Lightweight, typed description of a theme (the TS manifest each theme ships). */

package/dist/activity-DT8VK9fx.d.ts

@@ -0,0 +1,25 @@
+/** One day of activity. Only `date` and `value` are required. */
+interface ActivityDay {
+    /** The calendar day, "YYYY-MM-DD". Read as a day, never as an instant. */
+    date: string;
+    /** The measure for that day. A day missing from the data counts as 0. */
+    value: number;
+    /** 0…levels-1. Overrides the computed level — GitHub's API sends its own. */
+    level?: number;
+    /** A key into the heatmap's `categories`, for multi-source cells. */
+    category?: string;
+}
+/** Days as a list, or as a map of date to value (GitLab's and Mantine's shape). */
+type ActivityData = ActivityDay[] | Record<string, number>;
+/**
+ * Several sources' days merged into one list with categories: a day active in
+ * one source takes that source's key, a day active in more than one takes
+ * `both`. Values sum. For "GitHub, Codex, or both on that day".
+ *
+ * @example mergeActivity({ github: githubDays, codex: codexDays })
+ */
+declare function mergeActivity(sources: Record<string, ActivityData>, { both }?: {
+    both?: string;
+}): ActivityDay[];
+
+export { type ActivityDay as A, type ActivityData as a, mergeActivity as m };