@sableui/react 0.16.0 → 0.18.0

package/scripts/adoption.mjs

@@ -0,0 +1,239 @@
+/**
+ * adoption — how much of an app's UI is actually built from Sable.
+ *
+ * Wiring can be perfect while the app composes none of it: an agent that never
+ * loaded the skill sees Tailwind and a stylesheet and writes its own Button, its
+ * own Modal, its own Tabs on top of Sable's tokens. Lint catches a raw
+ * `<button>` with classes; it cannot see that `function Modal()` is a dialog
+ * Sable already ships, or that forty UI files import nothing from the package.
+ *
+ * This reads the source lexically, like grade, and answers three things:
+ *
+ *   - level: how many UI files compose Sable at all
+ *   - swaps: app-defined components named for something Sable ships, which the
+ *            file does not itself build on (behaviour first: those are where
+ *            focus, keyboard and ARIA bugs live)
+ *   - foundation: "sable" when Sable already carries the UI; otherwise whether
+ *            the app has its own system to respect (another UI library, or a
+ *            folder of its own primitives) or is ad hoc
+ *
+ * It never fails anything. It is the evidence an agent shows the user when it
+ * asks whether to move app-built UI onto Sable, and the wording of that ask
+ * depends on the foundation: firm when there is none, gentle when there is one.
+ */
+
+/** Groups whose components own behaviour (focus, keyboard, ARIA). */
+const BEHAVIOUR_GROUPS = new Set(["Actions", "Forms", "Overlays", "Navigation", "Selection"])
+const BEHAVIOUR_NAMES = new Set(["Accordion", "Collapsible", "Carousel", "Toast", "DataTable", "CommandMenu"])
+
+/** Other component libraries, by import specifier. */
+const LIBRARIES = [
+	[/^@mui\//, "MUI"],
+	[/^@chakra-ui\//, "Chakra UI"],
+	[/^antd(?:$|\/)/, "Ant Design"],
+	[/^@mantine\//, "Mantine"],
+	[/^react-bootstrap(?:$|\/)/, "React Bootstrap"],
+	[/^@headlessui\//, "Headless UI"],
+	[/^@radix-ui\//, "Radix"],
+	[/^@(?:nextui-org|heroui)\//, "HeroUI"],
+	[/^(?:react-aria-components$|@react-aria\/)/, "React Aria"],
+	[/^primereact(?:$|\/)/, "PrimeReact"],
+	[/^flowbite-react(?:$|\/)/, "Flowbite"],
+	[/^@ark-ui\//, "Ark UI"],
+]
+/** shadcn/ui-style primitives: `@/components/ui/button`, `../components/ui/dialog`. */
+const SHADCN = /(?:^|\/)components\/ui\/[a-z][\w-]*$/
+/** Where an app keeps a system of its own. */
+const PRIMITIVES_DIR = /(?:^|\/)(?:ui|primitives|design-system|ds)\//i
+/** Names that are an app's own structure, never a control it rebuilt. */
+const STRUCTURAL = /^(?:App|Root|Main|Home|Index)$|(?:Page|Layout|Provider|Context|Screen|View|Routes?|Router|Story|Stories|Demo|Example|Icon|Logo)$/
+
+const IMPORT = /import\s+(?:type\s+)?([\s\S]*?)\s+from\s*["']([^"']+)["']/g
+const DECLARATIONS = [
+	/(?:^|\n)[ \t]*(?:export\s+(?:default\s+)?)?function\s+([A-Z]\w*)\s*[(<]/g,
+	/(?:^|\n)[ \t]*(?:export\s+)?const\s+([A-Z]\w*)\s*(?::[^=\n]+)?=\s*(?:React\.)?(?:forwardRef|memo)\b/g,
+	/(?:^|\n)[ \t]*(?:export\s+)?const\s+([A-Z]\w*)\s*(?::[^=\n]+)?=\s*(?:async\s*)?\([^)]*\)\s*(?::[^=\n]+)?=>/g,
+]
+
+const normalize = (s) => s.toLowerCase().replace(/[\s_-]+/g, "")
+const words = (name) => name.match(/[A-Z]+(?![a-z])|[A-Z]?[a-z0-9]+/g) ?? [name]
+/**
+ * Behaviour done by hand, on native elements: what makes a component named
+ * Modal or Tabs a rebuild rather than content handed to Sable's (a tooltip
+ * body for ActivityHeatmap) or a composition of Sable's own controls (a
+ * toolbar of Pill, Select and SearchInput). Handlers on a capitalised tag
+ * belong to that component, so only lowercase tags count.
+ */
+const HAND_BEHAVIOUR = [
+	/<(?:button|input|select|textarea|dialog|details)\b/,
+	/<[a-z][a-z0-9]*\b[^<>]*\son(?:Click|KeyDown|KeyUp|MouseEnter|MouseLeave|PointerDown|PointerEnter|Focus|Blur)\s*=/,
+	/<[a-z][a-z0-9]*\b[^<>]*\srole=["'](?:dialog|alertdialog|tablist|tab|tabpanel|menu|menubar|menuitem|listbox|option|combobox|switch|slider|tooltip|checkbox|radio|radiogroup)["']/,
+	/<[a-z][a-z0-9]*\b[^<>]*\saria-(?:expanded|modal|selected|haspopup|pressed|checked)=/,
+	/\bcreatePortal\s*\(/,
+	/className=["'`][^"'`]*\bfixed\b[^"'`]*\binset-/,
+]
+const isBehaviour = (c) => BEHAVIOUR_GROUPS.has(c.group) || BEHAVIOUR_NAMES.has(c.name)
+const lineOf = (text, index) => text.slice(0, index).split("\n").length
+
+/**
+ * A .tsx/.jsx file that renders markup: a closing tag, or a self-closing `/>`
+ * (matched bare, since an arrow handler's `=>` sits inside the tag).
+ */
+const rendersJsx = (text) => /<\/[A-Za-z][\w.]*\s*>|\/>/.test(text)
+
+/**
+ * The names apps give the controls they rebuild, mapped to Sable's. Curated
+ * rather than read from registry keywords: those are written for search, so
+ * "list", "panel" and "preview" tie half an app's own components to something.
+ */
+const ALIASES = {
+	modal: ["Dialog"], dropdown: ["Menu", "Select"], dropdownmenu: ["Menu"], popup: ["Popover"],
+	drawer: ["Sheet"], sidesheet: ["Sheet"], bottomsheet: ["Sheet"], snackbar: ["Toast"], notification: ["Toast"],
+	spinner: ["Spinner"], loader: ["Spinner", "Skeleton"], progressbar: ["Progress"], autocomplete: ["Combobox"],
+	typeahead: ["Combobox"], multiselect: ["Combobox"], textfield: ["Input"], textinput: ["Input"], searchbar: ["SearchInput"],
+	searchbox: ["SearchInput"], searchfield: ["SearchInput"], iconbutton: ["Button"], fileupload: ["FileDropzone"],
+	uploader: ["FileDropzone"], dropzone: ["FileDropzone"], collapse: ["Collapsible"], disclosure: ["Collapsible"],
+	commandpalette: ["CommandMenu"], datepicker: ["DatePicker"], toggleswitch: ["Switch"], segmentedcontrol: ["Tabs", "ButtonGroup"],
+	tabbar: ["Tabs", "BottomNav"], navbar: ["AppHeader", "NavigationMenu"], topbar: ["AppHeader"], breadcrumb: ["Breadcrumbs"],
+	chip: ["Pill", "Badge"], tag: ["Badge"], alert: ["Banner"], callout: ["Note"], confirmdialog: ["DestructiveActionModal", "Dialog"],
+	contextmenu: ["ContextMenu"], hovercard: ["ContextCard"], numberinput: ["NumberField"], otpinput: ["OtpField"], pininput: ["OtpField"],
+	colorpicker: ["ColorField"], rating: ["RadioCard"], stepper: ["Stepper"], wizard: ["Stepper"], kbd: ["Kbd"],
+}
+
+/**
+ * The Sable components an app-defined name stands for: its whole name or its
+ * last word or two, as a Sable name (`Button`, `PrimaryButton`) or an alias
+ * (`Modal`, `SearchModal` → Dialog).
+ */
+function matcher(components) {
+	const byName = new Map(components.map((c) => [c.name.toLowerCase(), c]))
+	return (appName) => {
+		if (STRUCTURAL.test(appName)) return []
+		const w = words(appName)
+		const candidates = [...new Set([appName, w.slice(-2).join(""), w.at(-1)].filter(Boolean).map(normalize))]
+		for (const key of candidates) {
+			if (byName.has(key)) return [byName.get(key)]
+			const alias = ALIASES[key]?.map((name) => byName.get(name.toLowerCase())).filter(Boolean)
+			if (alias?.length) return alias
+		}
+		return []
+	}
+}
+
+/**
+ * @param {{ files: { rel: string, text: string }[], components: object[], deps?: Record<string, string> | null }} input
+ *   files: the app's .tsx/.jsx sources, paths relative to the project.
+ */
+export function adoptionReport({ files, components, deps = null }) {
+	const match = matcher(components)
+	const sableUsed = new Set()
+	const libraries = new Map()
+	let uiFiles = 0
+	let sableFiles = 0
+	let ownPrimitives = 0
+	const swaps = []
+
+	for (const { rel, text } of files) {
+		if (!/\.(tsx|jsx)$/.test(rel) || !rendersJsx(text)) continue
+		uiFiles++
+		const imported = new Set()
+		for (const m of text.matchAll(IMPORT)) {
+			const from = m[2]
+			if (/^@sableui\/react(?:\/|$)/.test(from)) {
+				for (const raw of (m[1].match(/\{([^}]*)\}/)?.[1] ?? "").split(",")) {
+					const name = raw.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim()
+					if (name) imported.add(name)
+				}
+				continue
+			}
+			const lib = LIBRARIES.find(([re]) => re.test(from))?.[1] ?? (SHADCN.test(from) ? "shadcn/ui-style components/ui" : null)
+			if (lib) libraries.set(lib, (libraries.get(lib) ?? 0) + 1)
+		}
+		if (imported.size) sableFiles++
+		for (const name of imported) sableUsed.add(name)
+
+		const declared = new Map()
+		for (const re of DECLARATIONS) for (const m of text.matchAll(re)) if (!declared.has(m[1])) declared.set(m[1], m.index + m[0].indexOf(m[1]))
+		// Each component's body runs to the next declaration: close enough to
+		// tell whose markup a handler or a role belongs to.
+		const starts = [...declared.values()].sort((a, b) => a - b)
+		const own = PRIMITIVES_DIR.test(rel)
+		for (const [name, index] of declared) {
+			const hits = match(name)
+			if (!hits.length) continue
+			if (own) ownPrimitives++
+			// Built on the Sable component it is named for: a composition, not a rebuild.
+			if (hits.some((c) => imported.has(c.name))) continue
+			const behaviour = hits.some(isBehaviour)
+			const body = text.slice(index, starts.find((s) => s > index) ?? text.length)
+			if (behaviour && !HAND_BEHAVIOUR.some((re) => re.test(body))) continue
+			swaps.push({ file: rel, line: lineOf(text, index), name, sable: hits.map((c) => c.name), behaviour })
+		}
+	}
+
+	// A dependency counts even before its first import is found in these paths.
+	for (const dep of Object.keys(deps ?? {})) {
+		const lib = LIBRARIES.find(([re]) => re.test(dep))?.[1]
+		if (lib && !libraries.has(lib)) libraries.set(lib, 0)
+	}
+
+	swaps.sort((a, b) => Number(b.behaviour) - Number(a.behaviour))
+	const share = uiFiles ? sableFiles / uiFiles : 0
+	const behaviourSwaps = swaps.filter((s) => s.behaviour).length
+	const level =
+		uiFiles === 0 ? "empty"
+		: sableFiles === 0 && uiFiles <= 2 ? "fresh"
+		: sableFiles === 0 ? "none"
+		: share < 0.5 || behaviourSwaps >= 3 ? "low"
+		: "sable"
+	const foundation = libraries.size ? "library" : level === "sable" ? "sable" : ownPrimitives >= 4 ? "own" : "ad-hoc"
+
+	return {
+		informationalOnly: true,
+		level,
+		foundation,
+		uiFiles,
+		sableFiles,
+		share: +share.toFixed(2),
+		sableComponents: [...sableUsed].sort(),
+		libraries: [...libraries].map(([name, files]) => ({ name, files })),
+		swaps,
+		summary: summaryOf({ level, uiFiles, sableFiles, sableUsed, swaps }),
+		recommendation: recommendationOf({ level, foundation, libraries, behaviourSwaps }),
+	}
+}
+
+function summaryOf({ level, uiFiles, sableFiles, sableUsed, swaps }) {
+	if (level === "empty") return "No UI files yet."
+	if (level === "fresh") return `${uiFiles} UI file(s), none using Sable yet. A starter: build on Sable from here.`
+	const built = swaps.length ? `; ${swaps.length} app-built component(s) named for something Sable ships` : ""
+	return `${sableFiles} of ${uiFiles} UI files compose Sable (${sableUsed.size} distinct export${sableUsed.size === 1 ? "" : "s"})${built}.`
+}
+
+/**
+ * What the agent should do with this, in words it can relay. Never "rewrite it":
+ * the user decides whether working screens move. The foundation decides how
+ * strongly to recommend it.
+ */
+function recommendationOf({ level, foundation, libraries, behaviourSwaps }) {
+	if (level === "empty" || level === "fresh") return "Build new UI from Sable: sable search \"<need>\" before writing a component."
+	const names = [...libraries.keys()].join(", ")
+	if (level === "sable")
+		return libraries.size
+			? `Sable is the foundation, alongside ${names}. Keep new UI on Sable; offer the swaps listed when a screen is next touched.`
+			: behaviourSwaps
+				? "Sable is the foundation. Offer the few swaps listed when those screens are next touched; new UI starts with sable search."
+				: "Sable is the foundation. Keep composing from it; new UI starts with sable search."
+	if (foundation === "library")
+		return `This app also builds on ${names}. Ask the user whether Sable should replace it or only cover new work; don't mix two control libraries on one screen.`
+	if (foundation === "own")
+		return "This app has its own primitives. Offer the swaps listed, behaviour first, and keep the app's own where the user prefers them."
+	return "This app has no component foundation besides Sable. Recommend moving the listed components onto Sable, behaviour first, and ask the user before changing working screens."
+}
+
+/** One line per swap, for text output. */
+export function swapLines(report, limit = 12, indent = "      ") {
+	const lines = report.swaps.slice(0, limit).map((s) => `${indent}${s.file}:${s.line}  ${s.name} → Sable has ${s.sable.join(" or ")}${s.behaviour ? " (behaviour)" : ""}`)
+	if (report.swaps.length > limit) lines.push(`${indent}… ${report.swaps.length - limit} more: sable grade <paths> --json → adoption.swaps`)
+	return lines
+}

package/scripts/agent-setup.mjs

@@ -40,6 +40,27 @@ const STOP_HOOK_MARKER = "sable check --stop-hook"
 const PORTABLE = /^[\w@./ -]+$/
 const quoted = (s) => (/^[\w./-]+$/.test(s) ? s : `"${s}"`)
 
+/**
+ * How to run this project's `sable` from `root`. A workspace package is reached
+ * through the package manager's own workspace flag, since its `sable` bin is not
+ * on the root's path.
+ */
+function sableRunner({ root, project }) {
+	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
+	const pm = packageManager(root, project)
+	if (projectPath) {
+		let name
+		try { name = JSON.parse(readFileSync(join(project, "package.json"), "utf8")).name } catch { /* unnamed */ }
+		if (typeof name === "string" && PORTABLE.test(name))
+			return {
+				pnpm: `pnpm --filter ${quoted(name)} exec sable`,
+				yarn: `yarn workspace ${quoted(name)} sable`,
+				npm: `npm exec --workspace ${quoted(name)} --no -- sable`,
+			}[pm]
+	}
+	return { pnpm: "pnpm exec sable", yarn: "yarn sable", npm: "npm exec --no -- sable" }[pm]
+}
+
 /**
  * The Claude Code Stop hook that runs `sable check` before a task can end:
  * settings.json → hooks.Stop[] → { hooks: [{ type: "command", command }] }.
@@ -51,27 +72,13 @@ const quoted = (s) => (/^[\w./-]+$/.test(s) ? s : `"${s}"`)
  * without it on Windows, PowerShell 5.1, which supports neither. `sable check
  * --stop-hook` reads CLAUDE_PROJECT_DIR from its environment instead, and
  * `--root` names the Sable package when the entries live at a repository root.
- * A workspace package is reached through the package manager's own workspace
- * flag, since its `sable` bin is not on the root's path.
+ * A workspace package is reached through sableRunner.
  */
 export function claudeStopHook({ root, project = root }) {
 	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
 	if (projectPath.startsWith("..") || isAbsolute(projectPath)) throw new Error("--root must be the project directory or one of its ancestors, such as the repository root.")
 	if (projectPath && !PORTABLE.test(projectPath)) throw new Error(`Unsupported characters for a portable hook in the project path: ${projectPath}. Add the hook by hand.`)
-	const pm = packageManager(root, project)
-	let runner = { pnpm: "pnpm exec sable", yarn: "yarn sable", npm: "npm exec --no -- sable" }[pm]
-	if (projectPath) {
-		let name
-		try { name = JSON.parse(readFileSync(join(project, "package.json"), "utf8")).name } catch { /* unnamed */ }
-		if (typeof name === "string" && PORTABLE.test(name)) {
-			runner = {
-				pnpm: `pnpm --filter ${quoted(name)} exec sable`,
-				yarn: `yarn workspace ${quoted(name)} sable`,
-				npm: `npm exec --workspace ${quoted(name)} --no -- sable`,
-			}[pm]
-		}
-	}
-	const command = `${runner} check --stop-hook${projectPath ? ` --root ${quoted(projectPath)}` : ""}`
+	const command = `${sableRunner({ root, project })} check --stop-hook${projectPath ? ` --root ${quoted(projectPath)}` : ""}`
 	const entry = { hooks: [{ type: "command", command, timeout: 300 }] }
 	return { settingsFile: ".claude/settings.json", command, entry, settings: { hooks: { Stop: [entry] } }, installed: false }
 }
@@ -110,6 +117,63 @@ export function installClaudeStopHook({ root, project = root, dryRun = false })
 	return { ...hook, installed: true, alreadyPresent }
 }
 
+const BLOCK_BEGIN = "<!-- sable:begin"
+const BLOCK_END = "<!-- sable:end -->"
+
+/**
+ * The always-loaded half of the setup. A skill loads only when the request
+ * names it or its description matches, so "make me a pricing page" in a wired
+ * app can skip it entirely: the agent sees Tailwind and a stylesheet and writes
+ * its own Button and Modal on Sable's tokens. Project instructions (AGENTS.md
+ * for Codex and Cursor, CLAUDE.md for Claude Code) are read on every task, so a
+ * few lines there send every UI request through the skill.
+ *
+ * Short on purpose: it is in context for every task, UI or not, so it points at
+ * the skill rather than restating it.
+ */
+export function instructionsBlock({ root, project = root }) {
+	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
+	const sable = sableRunner({ root, project })
+	const where = projectPath ? `The UI in \`${projectPath}\`` : "This app's UI"
+	return [
+		`${BLOCK_BEGIN} — managed by \`sable setup --agent\`; edit outside these markers -->`,
+		"## Sable",
+		"",
+		`${where} is built with Sable (\`@sableui/react\`). For any UI work (a page, a component, styling, layout, theming, a fix), load the \`sable\` skill first: \`/sable\` in Claude Code and Cursor, \`$sable\` in Codex. Do this even when the request does not mention Sable.`,
+		"",
+		`- Build from the installed components, utilities and tokens: \`${sable} search "<need>"\` before writing a component. Never rebuild a control Sable ships.`,
+		`- Before calling UI work done, run \`${sable} check\` and fix what fails.`,
+		"- When `check` lists app-built components that Sable already ships (Adoption), show the user that list and ask before moving working screens onto Sable.",
+		BLOCK_END,
+	].join("\n")
+}
+
+/** The managed block in `text`, as [start, end) offsets, or null. */
+function findBlock(text) {
+	const start = text.indexOf(BLOCK_BEGIN)
+	if (start === -1) return null
+	const end = text.indexOf(BLOCK_END, start)
+	if (end === -1) throw new Error("A Sable block in the project instructions has no end marker. Fix or remove it, then rerun setup.")
+	return [start, end + BLOCK_END.length]
+}
+
+/**
+ * Which project-instruction files carry the block, per host: AGENTS.md for
+ * Codex and Cursor, CLAUDE.md for Claude Code. A CLAUDE.md that already imports
+ * AGENTS.md (`@AGENTS.md`) gets the block through that import, not twice.
+ */
+function instructionFiles(root, target) {
+	const agents = target === "all" || target === "codex" || target === "cursor"
+	const claude = target === "all" || target === "claude"
+	const files = agents ? ["AGENTS.md"] : []
+	if (claude) {
+		const claudePath = join(root, "CLAUDE.md")
+		const imports = existsSync(claudePath) && /^@(?:\.\/)?AGENTS\.md\s*$/m.test(readFileSync(claudePath, "utf8"))
+		if (!(agents && imports)) files.push("CLAUDE.md")
+	}
+	return files
+}
+
 /**
  * Install discoverable loaders; the installed package owns the actual workflow.
  *
@@ -117,7 +181,7 @@ export function installClaudeStopHook({ root, project = root, dryRun = false })
  * is where the agent entries go. They differ in a monorepo, where agents start at
  * the repository root but Sable belongs to one workspace package.
  */
-export function installAgentSkill({ root, project = root, packageRoot, target = "all", update = false, dryRun = false }) {
+export function installAgentSkill({ root, project = root, packageRoot, target = "all", update = false, dryRun = false, instructions = true }) {
 	const reject = (message) => { throw new Error(message) }
 	if (!["all", "codex", "claude", "cursor"].includes(target)) reject("Choose --target all, codex, claude, or cursor.")
 	if (!existsSync(join(project, "package.json"))) reject("Run setup from a project with a package.json.")
@@ -158,14 +222,42 @@ export function installAgentSkill({ root, project = root, packageRoot, target =
 		if (current === file.content) continue
 		if (!update || receipt.files[file.path] !== hash(current)) reject(`Existing skill differs at ${file.path}. Use --update for managed files; keep or move local edits before setup.`)
 	}
+	/* The block in AGENTS.md / CLAUDE.md. Only the text between its markers is
+	 * Sable's; everything around it is the project's and is never touched. It
+	 * follows the skill files' rule: an unchanged older block refreshes under
+	 * --update, one with local edits refuses. */
+	const block = instructions ? instructionsBlock({ root, project }) : null
+	const instructionPaths = block ? instructionFiles(root, target) : []
+	const edits = []
+	for (const path of instructionPaths) {
+		checkPath(path)
+		const key = `${path}#sable`
+		const current = existsSync(join(root, path)) ? readFileSync(join(root, path), "utf8") : null
+		const eol = current?.includes("\r\n") ? "\r\n" : "\n"
+		const ours = block.replaceAll("\n", eol)
+		const found = current === null ? null : findBlock(current)
+		if (found) {
+			const existing = current.slice(...found)
+			if (existing === ours) continue
+			if (!update || receipt.files[key] !== hash(existing.replaceAll("\r\n", "\n"))) reject(`The Sable block in ${path} differs. Use --update to refresh it; keep local edits outside its markers.`)
+			edits.push({ path, key, content: current.slice(0, found[0]) + ours + current.slice(found[1]) })
+		} else if (current === null) edits.push({ path, key, content: `${block}\n` })
+		else edits.push({ path, key, content: `${current.replace(/\s*$/, "")}${eol}${eol}${ours}${eol}` })
+	}
 	if (!dryRun) {
 		for (const file of files) {
 			mkdirSync(dirname(join(root, file.path)), { recursive: true })
 			writeFileSync(join(root, file.path), file.content)
 			receipt.files[file.path] = hash(file.content)
 		}
+		for (const edit of edits) {
+			writeFileSync(join(root, edit.path), edit.content)
+			receipt.files[edit.key] = hash(block)
+		}
 		mkdirSync(dirname(join(root, receiptPath)), { recursive: true })
 		writeFileSync(join(root, receiptPath), JSON.stringify(receipt, null, 2) + "\n")
 	}
-	return { destination: destinations[0], destinations, root, project: projectPath || ".", files: files.map(file => file.path), dryRun, update, next: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
+	return { destination: destinations[0], destinations, root, project: projectPath || ".", files: files.map(file => file.path), instructions: instructionPaths, instructionsChanged: edits.map(edit => edit.path), dryRun, update, next: block
+		? "Ask your agent for what you want to build or change, in plain words. It uses Sable on its own; /sable (Codex: $sable) names it explicitly."
+		: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
 }

package/scripts/grade.mjs

@@ -37,6 +37,7 @@ import { ignoreGlob, lintText, makeRules, surfaceInventory } from "./lint-rules.
 import { labelContrastScanner, statusTextDrift } from "./label-contrast.mjs"
 import { skeletonize } from "./skeleton.mjs"
 import { assessReview, reviewTemplate } from "./review-evidence.mjs"
+import { adoptionReport, swapLines } from "./adoption.mjs"
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = join(HERE, "..")
@@ -375,6 +376,8 @@ const routeSkeletons = []
    of listing from memory. The lookalike-* lint rules fail the unambiguous
    cases; this lists the rest. */
 const inventory = []
+/** UI sources for the adoption report: how much of the app is built from Sable. */
+const uiSources = []
 
 /**
  * Attribute names on one JSX open tag, stopping at the tag's own `>`.
@@ -502,6 +505,7 @@ for (const file of files) {
 
 	/* 7. Surfaces the app built itself (informational). */
 	if (/\.(tsx|jsx)$/.test(file)) {
+		uiSources.push({ rel, text })
 		for (const { index, ...s } of surfaceInventory(text)) inventory.push({ file: rel, line: lineOf(text, index), ...s })
 		// Arrow-key handling written by hand: list navigation is behaviour Sable
 		// owns (roving focus, active descendant, typeahead), and the storefront
@@ -632,6 +636,12 @@ if (reviewPath) {
 }
 const review = assessReview(reviewDocument, { baseDir: reviewPath ? dirname(resolve(CWD, reviewPath)) : CWD, sourceHash })
 const clean = !Object.values(counts).some(Boolean)
+let appDeps = null
+try {
+	const pkg = JSON.parse(readFileSync(join(CWD, "package.json"), "utf8"))
+	appDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+} catch { /* no package.json here: imports alone decide */ }
+const adoption = adoptionReport({ files: uiSources, components: REGISTRY.components ?? [], deps: appDeps })
 const exitCode = flags.has("strict") && (!clean || review.status !== "review-recorded") ? 1 : 0
 
 const result = {
@@ -655,6 +665,7 @@ const result = {
 		byKind: Object.fromEntries(["surface", "media frame", "round"].map((k) => [k, inventory.filter((s) => s.kind === k).length])),
 		surfaces: inventory,
 	},
+	adoption,
 	cliUsage,
 	appIcons: APP_ICONS ? { file: APP_ICONS.file, names: APP_ICONS.names.size } : null,
 	findings,
@@ -696,6 +707,12 @@ if (inventory.length) {
 	for (const s of inventory.slice(0, 12)) L(`    ${s.file}:${s.line}  <${s.tag}> ${s.kind} (${s.classes}) → Sable has ${s.consider}`)
 	if (inventory.length > 12) L(`    … ${inventory.length - 12} more (--json lists every one)`)
 }
+if (adoption.level !== "empty") {
+	L()
+	L(`  adoption (notes, not scored) — ${adoption.level}: ${adoption.summary}`)
+	L(`    ${adoption.recommendation}`)
+	for (const line of swapLines(adoption, 12, "    ")) L(line)
+}
 if (cliUsage) {
 	L()
 	L(`  sable CLI                   ${cliUsage.invocations} invocation(s)`)

package/scripts/wiring.mjs

@@ -303,7 +303,8 @@ function addTailwindPlugin(text) {
  */
 export function fixWiring({ root, pkgRoot, report, framework, dryRun = false, install = true, quiet = false }) {
 	const results = []
-	const flagged = new Map(report.checks.filter((c) => c.status === "fail" || c.status === "warn" || (c.status === "info" && c.name === "dedupe")).map((c) => [c.name, c]))
+	// Adoption is how the app is built, not how it is wired: no fix of ours applies.
+	const flagged = new Map(report.checks.filter((c) => c.name !== "adoption" && (c.status === "fail" || c.status === "warn" || (c.status === "info" && c.name === "dedupe"))).map((c) => [c.name, c]))
 	const handled = new Set()
 	const done = (check, detail, file) => {
 		handled.add(check)

package/skills/entry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sable
-description: Build websites and apps with Sable, develop reusable presets from inspiration, audit interfaces, polish designs, and fix scoped defects using the installed library.
+description: Use for any UI work in a project that depends on @sableui/react (a page, a component, styling, layout, theming, or a UI fix), even when the request does not mention Sable. Builds websites and apps from the installed Sable library, develops reusable presets from inspiration, audits and polishes interfaces, and fixes scoped defects.
 ---
 
 # Sable

package/skills/sable/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sable
-description: Build original websites and apps with Sable, turn inspiration into reusable presets, audit existing interfaces, polish a selected design, and fix a scoped defect on a short path. Use for Sable design and UI work, not unrelated backend tasks.
+description: Use for any UI work in a project that depends on @sableui/react (a page, a component, styling, layout, theming, or a UI fix), even when the request does not mention Sable. Builds websites and apps from the installed Sable library, turns inspiration into reusable presets, audits and polishes existing interfaces, and fixes scoped defects. Not for unrelated backend tasks.
 ---
 
 # Sable
@@ -35,7 +35,9 @@ the check turns up more than the fix. Say that you escalated, and why.
    `sable lint`, and `sable grade` and exits 1 if any fails. Repair the findings
    instead of suppressing them, then run it again until it passes. Act on its
    notes too: they don't fail the check but name real work, such as trimming the
-   CSS to the components the app imports (`sable sources`). Also run the
+   CSS to the components the app imports (`sable sources`), or an Adoption block
+   listing app-built components Sable already ships, which you put to the user
+   (see "Adoption" under Verify and deliver). Also run the
    project's own build and type checks.
 2. Review the rendered design: `sable docs reviewing-a-design`. Capture desktop and
    mobile in every promised colour mode, and judge brief fit, composition,
@@ -64,6 +66,9 @@ results, plus any step its notes call for. A passing check is a contract result,
 
 These are agent skill modes, not shell commands. Use `$sable` in Codex and
 `/sable` in Claude Code or Cursor; natural requests work in compatible agents.
+A request that never says "Sable" ("add a pricing page", "make the header
+sticky") in a project that depends on `@sableui/react` is still this skill:
+route it by the rules below and build it from the library.
 
 | Mode | Outcome |
 | --- | --- |
@@ -75,6 +80,11 @@ These are agent skill modes, not shell commands. Use `$sable` in Codex and
 
 `create` is an alias for `build`. A bare new-product brief means `build`; an editing
 follow-up means `polish`, unless it names one defect, which is a `fix`. A request for direction only stops before implementation.
+"Move this app onto Sable" (or convert, migrate, "use Sable properly") is never
+a `build`: that would start the product over. Run `sable check`, show the user
+the Adoption swaps in one short list, ask once which to move, then `polish` them
+a screen at a time without asking again for each. The user should not need to
+know the mode names; route plain requests yourself.
 “Show alternatives” produces bounded rendered studies and stops at comparison when
 the user reserves the choice. Explore only when requested or when competing choices
 materially affect the brief; do not require three designs for every build.
@@ -151,7 +161,11 @@ rather than redoing it:
 
 `sable init` installs the discoverable entry files for Codex/Cursor and Claude
 Code; in an app wired by hand, run `sable setup --agent` once from the project root. `--target codex|claude|cursor|all` selects
-hosts. For Claude Code, setup also prints a Stop hook that runs `sable check`
+hosts. Setup also writes a short managed block into `AGENTS.md` and `CLAUDE.md`,
+the instructions every task reads, that sends UI requests through this skill
+even when they don't name it. It replaces only the text between its
+`<!-- sable:begin … -->` and `<!-- sable:end -->` markers; `--no-instructions`
+skips it. For Claude Code, setup also prints a Stop hook that runs `sable check`
 before a task can end; it writes that hook to `.claude/settings.json` only with
 `--hook`, so add it only when the user wants it. The hook is one plain command
 (for example `pnpm exec sable check --stop-hook`) with no `cd` or `&&`, so it runs
@@ -213,7 +227,8 @@ The installed catalog and guides are authoritative for API and token names.
    consume it. In another app, implement only genuinely app-specific structure;
    report a missing library hook. Do not modify installed package files or build
    parallel controls as a shortcut. Preserve existing non-Sable work unless a
-   migration was requested.
+   migration was requested, but don't leave it unmentioned: when `sable check`
+   reports adoption `none` or `low`, ask the user (see "Adoption" below).
 
 ## Develop or use a preset
 
@@ -281,6 +296,20 @@ contract violations, design judgments, intentional choices, and verified library
 gaps. A visual-only review leaves code and unobserved behavior untested. For
 `polish`, reuse the existing direction and inspect the affected product or preset.
 
+**Adoption.** An app can be wired for Sable and barely use it: an earlier agent
+never loaded this skill and wrote its own Modal, Button and Tabs on Sable's
+tokens. `sable check` reports it under Adoption (`sable grade --json` →
+`adoption`): how many UI files compose Sable, the app-built components Sable
+already ships (behaviour first), and the app's `foundation`. When the level is
+`none` or `low`, during any mode, ask the user before moving working screens, with
+the host's question tool if it has one. Show the swaps and what each gains
+("your Modal has no focus trap or Esc; Sable's Dialog has both"). Recommend the
+move plainly when the foundation is `ad-hoc`; offer it gently when the app has
+its `own` primitives; ask whether Sable replaces another `library` or only covers
+new work. Record the answer in the project's instructions, outside the Sable
+block, so the next task doesn't ask again. `sable docs auditing-an-app` has the
+full guide.
+
 Every build and polish ends with the finish checklist near the top of this skill. Notes on it:
 
 - `sable check` gives one combined result; while iterating, `sable lint <paths> --json`,

package/skills/sable/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Sable"
-  short_description: "Build, develop presets, audit, and polish with Sable"
+  short_description: "Any UI work in a Sable app: build, presets, audit, polish, fix"
   default_prompt: "Use $sable build to create my idea with the installed Sable components, tokens, and design guides, then inspect and polish the working result."
 policy:
   allow_implicit_invocation: true

package/targets/ios.json

@@ -78,6 +78,15 @@
       ],
       "guidance": "Use the Sable component as it is, in the preset. Adapt layout and touch targets to the phone; do not swap in a native lookalike or restyle it."
     },
+    "ActivityHeatmap": {
+      "source": "ActivityHeatmap",
+      "strategy": "preserve",
+      "importFrom": "@sableui/react",
+      "components": [
+        "ActivityHeatmap"
+      ],
+      "guidance": "Use the Sable component as it is, in the preset. Adapt layout and touch targets to the phone; do not swap in a native lookalike or restyle it."
+    },
     "AppHeader": {
       "source": "AppHeader",
       "strategy": "replace",
@@ -913,6 +922,15 @@
       ],
       "guidance": "Use the Sable component as it is, in the preset. Adapt layout and touch targets to the phone; do not swap in a native lookalike or restyle it."
     },
+    "SectionRail": {
+      "source": "SectionRail",
+      "strategy": "preserve",
+      "importFrom": "@sableui/react",
+      "components": [
+        "SectionRail"
+      ],
+      "guidance": "Use the Sable component as it is, in the preset. Adapt layout and touch targets to the phone; do not swap in a native lookalike or restyle it."
+    },
     "SegmentedBar": {
       "source": "SegmentedBar",
       "strategy": "preserve",