@sableui/react 0.16.0 → 0.18.0

package/AGENTS.md

@@ -153,6 +153,11 @@ In a monorepo where Sable belongs to one workspace package, run setup in that
 package with `--root` naming the repository root (for example
 `pnpm --filter web exec sable setup --agent --root ../..`); the entries go
 there and resolve Sable through the package.
+Setup also adds a short managed block to the project's `AGENTS.md` and
+`CLAUDE.md`, the instructions an agent reads on every task, so a UI request
+goes through the skill even when it doesn't mention Sable. Only the text between
+its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is Sable's;
+`--no-instructions` skips it.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`,
@@ -160,9 +165,11 @@ Use `$sable build <idea>`, `inspire <references>`, `audit <target>`,
 Claude Code or Cursor. `create` is a build alias. `fix` takes the short path for
 one scoped defect and escalates to `polish` when the change grows. These are agent modes, not shell commands.
 
-Upgrade with `pnpm update @sableui/react --latest`, then
-`pnpm exec sable setup --agent --update`. Setup only replaces managed files
-that have not been locally edited; `--dry-run` checks without writing. Keep
+Upgrade with `pnpm exec sable upgrade`: it updates the package, then runs the
+new version's `init`, which refreshes the skill entries and the instructions
+block and checks the wiring. From 0.17 or earlier, which has no `upgrade`, run
+`pnpm update @sableui/react --latest` and then `pnpm exec sable init` once.
+Setup only replaces managed files that have not been locally edited; `--dry-run` checks without writing. Keep
 project preferences in project instructions. Package installation alone does not
 change agent settings. See [building-with-sable.md](./llms/tasks/building-with-sable.md),
 [creating-a-preset.md](./llms/tasks/creating-a-preset.md), and

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # What's new
 
+## 0.18.0
+
+A year at a glance: the contribution graph, built so a phone, a keyboard and a
+screen reader can all read it.
+
+- **New: `ActivityHeatmap`.** A calendar heatmap: one value per day as a grid
+  of weeks by weekdays — the GitHub contribution graph, for any daily measure.
+  Pass days as `"YYYY-MM-DD"` with a value (or a date-to-value map); levels
+  come by quartile, as GitHub's do, unless a day brings its own. `categories`
+  colour days by source instead of intensity, and `mergeActivity` tags each day
+  with its source or `both`. The grid is a real `role="grid"` table with one
+  tab stop: arrows step a day or a week, each cell is named with its date and
+  value, and the tooltip shows on hover, focus and tap. It fills the width down
+  to `size`; narrower, the weeks scroll sideways and open on the latest, while
+  the weekday labels stay outside the scroller. Days are read as calendar days,
+  never instants, so no time zone shifts one. Prompted by a consumer site that
+  hand-built one from 371 buttons and broke on phones.
+- **New: `@sableui/react/adapters/github`.** `fromGitHubGraphQL` and
+  `fromGitHubContributionsApi` turn GitHub's contribution data into heatmap
+  days. Pure transforms: fetch on your server and pass the result in.
+- **New: `activityLevels` and `activityGrid`.** The level scale and the week
+  grid behind the heatmap, exported for a custom legend, a summary stat or
+  another layout.
+- **`ChartTooltipContent` with no rows** draws just its label, so a caller's
+  own content sits on the standard tooltip card.
+- **Layout primitives take `className` over their own layout.** Row, Stack,
+  Grid, Columns, Col, Center, Region, Page, Bleed, AspectBox, Spacer, SplitPane
+  and GridOverlay set `display`, direction, alignment, gap, inset, cap, ratio and
+  size inline, and an inline declaration beats every utility, so
+  `<Row className="max-lg:hidden">` or `hidden md:flex` silently did nothing.
+  The grid and split rules in `styles.css` were unlayered too, so `hidden` lost
+  to them whatever its specificity. Layout now lives in classes merged through
+  `cn()`, with prop values passed as CSS variables those classes read, and the
+  layout rules sit in `@layer components`. A utility in `className` wins at any
+  breakpoint (`max-md:flex-col`, `md:gap-6`, `lg:grid-cols-3`); the props work
+  as before. Migration: a `className` that used to be ignored on a primitive now
+  applies, and a test reading `style.gap` or `style.maxWidth` reads
+  `--sable-row-gap`, `--sable-region-max` and the like instead.
+- **`PageHeader size="lg"`.** A display-size page title for an editorial page
+  (a personal site, a marketing page, an article index): `text-display-lg` over
+  a `text-body-lg` lede capped at the prose measure. `md`, the default, is
+  unchanged. Keep `lg` off app routes: display type stays out of product chrome.
+- **`SectionHeader size="lg"`.** The major-section tier, `text-heading-2` over a
+  `text-body-md` description, for an editorial page's sections under a
+  `PageHeader size="lg"`. It stops at heading-2 because heading-1 is the page
+  title's, one per route. Actions stay centred on the title's first line at
+  every size.
+- **`SearchInput` takes `size`** (`md` | `sm` | `xs`), on the same ladder as
+  Input, Select and Combobox. `sm` is the toolbar field on `--control-sm`, `xs`
+  the inset tool-panel field; the magnifier, padding and clear button scale with
+  it and stay centred. Before, it was fixed at 40px and matched nothing in a
+  toolbar.
+- **`Pill size="lg"`.** A 32px chip on `--control-sm`, the toolbar height Button
+  `sm` and SearchInput `sm` share, so a filter row beside a search field is one
+  height in either density.
+- **`MediaImage` and `MediaTile` take a crop focus.** `position` sets where the
+  image sits in its frame and takes any CSS `object-position` value
+  (`"35% 50%"`, `"top"`), beside `fit`. MediaTile forwards it to its cover.
+- **Dialogs return focus to whatever opened them.** `Dialog`, `AlertDialog` and
+  `Sheet` record the element focused when `open` turns true and send focus back
+  to it on close, with or without a trigger. Before, a dialog opened from your
+  own button lost focus to the page whenever a field inside autofocused,
+  CommandMenu's included. An explicit `finalFocus` still wins.
+- **`DialogContent keepMounted`.** Keeps a closed dialog's content mounted and
+  hidden, so a half-written draft survives Esc or a stray click and is still
+  there on reopen. Opt in for drafts the user may come back to.
+- **Eight more icon names.** `briefcase`, `layers`, `microphone`, `video`,
+  `broadcast`, `newspaper`, `palette` and `gamepad` join the contract, mapped
+  in the Reicon set, for a portfolio that imported reicon-react directly for
+  its work, audio, video, live, press, design and games sections.
+- **Setup writes the skill into the instructions every task reads.** A skill
+  loads only when a request names it, so "add a pricing page" in a wired app
+  could skip it: the agent saw Tailwind and a stylesheet, wrote its own Button
+  and Modal, and put Sable's tokens on them. `sable setup --agent` (and `sable
+  init`) now also writes a short managed block into `AGENTS.md` and
+  `CLAUDE.md` that sends every UI request through the skill. Only the text
+  between its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is
+  Sable's; `--no-instructions` skips it. **Migration:** from 0.17, run
+  `pnpm update @sableui/react --latest` then `pnpm exec sable init` once; after
+  that, `sable upgrade` does both.
+- **New: `sable upgrade`.** One command to update: installs the latest
+  `@sableui/react` with the project's package manager, then runs the new
+  version's `init`, so the skill entries, the instructions block and the
+  checks are the new release's. Safe on an app that already works.
+- **"Move this app onto Sable" is a request the skill understands.** It checks
+  the app, shows the swaps once, asks, and moves them a screen at a time; it
+  never starts a new build. `init` says so when an app's UI barely uses Sable,
+  and its next step for a ready app is now a plain request, not mode syntax.
+- **Adoption, in `sable check`, `sable grade` and `sable doctor`.** How much of
+  the UI composes Sable, which app-built components do by hand what a Sable
+  component already does (a `Modal` → Dialog, a `SearchBar` → SearchInput,
+  behaviour first), and what the app already stands on: nothing, its own
+  primitives, or another library. Never a failure. `check` lists the swaps and,
+  when adoption is low, makes "ask the user about moving onto Sable" the first
+  review step; `doctor` warns. The skill and `sable docs auditing-an-app` say
+  how to put the choice to the user, more firmly when the app has no
+  foundation of its own.
+- **The skill triggers on any UI work in a Sable app.** Its description now
+  says so, even when the request doesn't mention Sable.
+- **`sable init --hook`.** Adds the Claude Code Stop hook that runs `sable
+  check` before a task can end. Run in a terminal, init asks; `--no-hook`
+  doesn't.
+- **`CodeBlock wrap`.** Wraps long lines instead of scrolling them, for prose
+  in a code face: a prompt to paste into an agent, a log line. Code keeps
+  scrolling.
+
+## 0.17.0
+
+Knowing where you are: a rail that follows a long read, and an approval
+that shows an agent's call the way agent products do.
+
+- **New: `SectionRail`.** A slim vertical rail of dots beside a long read —
+  a case study, an essay, a long landing page — one per section. A bar marks
+  the section being read and glides to the next as the page scrolls; hovering
+  or focusing a dot names it in one tooltip that travels between dots
+  (`TooltipGroup`). Picking a dot jumps there with the page's own
+  `scroll-behavior` (instant under reduced motion), and the bar goes straight
+  to the pick rather than stepping through every section in between. Pass
+  `root` when the content scrolls inside an element: only that element moves,
+  never the page around it. Links are real `#id` anchors, so it works without
+  script. Promoted from carldecaire.com's case-study rail.
+- **New: `useActiveSection(ids, { offset, root })`.** The scroll spy behind it,
+  exported for a contents list you draw yourself. The current section is the
+  last whose top has crossed the reading line; at the end of the scroll the
+  last one in view wins, so a short closing section is still reachable.
+- **`ApprovalBlock` asks the way agent products do.** It wraps the call's own
+  `ToolCall` — tool name and exact input, open on arrival — that turns to
+  Allowed or Denied once answered, and offers Deny / Always allow / Allow once.
+  The details table and the "for the rest of this chat" checkbox are gone;
+  `onApprove({ remember })` is unchanged, with `remember` now true for Always
+  allow. The example is an agent asking to run a command.
+
 ## 0.16.0
 
 Five pieces of the calm, product-chrome look that AI and B2B tools share:

package/README.md

@@ -69,7 +69,7 @@ pnpm add @sableui/react
 pnpm exec sable init        # or: npx sable init — once the package is installed
 ```
 
-`init` reads your package manager from the lockfile and your framework from the project. It installs what is missing (React, Tailwind and its build plugin), puts the CSS imports below in order, adds React dedupe and the Tailwind plugin to a Vite config, loads the fonts, mounts `IconProvider` in a Vite starter's entry, installs the agent skill (`sable setup --agent`), then runs `sable doctor`. Anything it cannot change safely — an unfamiliar config, a Next.js layout — it prints as the exact snippet and the file it belongs in. Vite and Next.js (App Router) get every step; other setups get the packages and the stylesheet. `--dry-run` shows every change first; `--no-agent` skips the skill. Already set up? `sable doctor --fix` applies the same fixes to whatever doctor flags.
+`init` reads your package manager from the lockfile and your framework from the project. It installs what is missing (React, Tailwind and its build plugin), puts the CSS imports below in order, adds React dedupe and the Tailwind plugin to a Vite config, loads the fonts, mounts `IconProvider` in a Vite starter's entry, installs the agent skill and its block in `AGENTS.md` / `CLAUDE.md` (`sable setup --agent`), offers the Claude Code Stop hook when you run it in a terminal, then runs `sable doctor`. Anything it cannot change safely — an unfamiliar config, a Next.js layout — it prints as the exact snippet and the file it belongs in. Vite and Next.js (App Router) get every step; other setups get the packages and the stylesheet. `--dry-run` shows every change first; `--no-agent` skips the skill. Already set up? `sable doctor --fix` applies the same fixes to whatever doctor flags.
 
 The steps below are what `init` does, for doing it by hand or checking its work.
 
@@ -213,6 +213,11 @@ In a monorepo where Sable belongs to one workspace package, run setup in that
 package with `--root` naming the repository root (for example
 `pnpm --filter web exec sable setup --agent --root ../..`); the entries go
 there and resolve Sable through the package.
+Setup also adds a short managed block to the project's `AGENTS.md` and
+`CLAUDE.md`, the instructions an agent reads on every task, so a UI request
+goes through the skill even when it doesn't mention Sable. Only the text between
+its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is Sable's;
+`--no-instructions` skips it.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
@@ -225,9 +230,11 @@ server: `claude mcp add --transport http sable https://www.sableui.com/api/mcp`
 and `docs`, give the CLI's answers from the published package, at the version
 the agent passes or the latest. Once Sable is installed, the CLI is the default.
 
-Upgrade with `pnpm update @sableui/react --latest`, then
-`pnpm exec sable setup --agent --update`. Setup only replaces managed files
-that have not been locally edited; `--dry-run` checks without writing. Keep
+Upgrade with `pnpm exec sable upgrade`: it updates the package, then runs the
+new version's `init`, which refreshes the skill entries and the instructions
+block and checks the wiring. From 0.17 or earlier, which has no `upgrade`, run
+`pnpm update @sableui/react --latest` and then `pnpm exec sable init` once.
+Setup only replaces managed files that have not been locally edited; `--dry-run` checks without writing. Keep
 project preferences in project instructions. Package installation alone does not
 change agent settings. See [building-with-sable.md](./llms/tasks/building-with-sable.md),
 [creating-a-preset.md](./llms/tasks/creating-a-preset.md), and

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"],
 	},
@@ -249,7 +252,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 +268,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 +377,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." },
@@ -1471,6 +1491,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 +1602,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 +1617,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 +1683,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 +1699,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
@@ -1751,7 +1866,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,
 	})
 
@@ -1807,14 +1923,20 @@ function cmdCheck() {
 	/* 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
+	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, manualReview: manual }
 	const MARK = { pass: "✓", fail: "✗", error: "✗" }
 	const MAX_DETAILS = 12
 	const summaryText = () =>
@@ -1840,6 +1962,16 @@ function cmdCheck() {
 			"",
 		].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 +2001,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()}${inventoryText()}${manualText()}\n`)
 	logInvocation(failed.length ? 1 : 0, failed.length ? "ERR_CHECK_FAILED" : undefined)
 	process.exit(failed.length ? 1 : 0)
 }
@@ -1899,6 +2031,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 +2049,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 +2063,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"])
 	}
@@ -1961,6 +2102,7 @@ const HANDLERS = {
 	docs: cmdDocs,
 	doctor: cmdDoctor,
 	init: cmdInit,
+	upgrade: cmdUpgrade,
 	grade: cmdGrade,
 	learn: cmdLearn,
 	atlas: () => cmdDesignTool("design-atlas.mjs"),

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 };

package/dist/adapters/github.d.ts

@@ -0,0 +1,41 @@
+import { A as ActivityDay } from '../activity-DT8VK9fx.js';
+
+/**
+ * GitHub contribution data → ActivityHeatmap days. Pure transforms: Sable never
+ * fetches. GitHub's GraphQL API needs a token, so call it from your server and
+ * pass the result through; the docs page shows a route handler that does.
+ */
+/** The `contributionLevel` enum GitHub's GraphQL API returns per day. */
+type GitHubContributionLevel = "NONE" | "FIRST_QUARTILE" | "SECOND_QUARTILE" | "THIRD_QUARTILE" | "FOURTH_QUARTILE";
+/** The slice of `user.contributionsCollection.contributionCalendar` the transform reads. */
+interface GitHubContributionCalendar {
+    weeks: {
+        contributionDays: {
+            date: string;
+            contributionCount: number;
+            contributionLevel?: GitHubContributionLevel;
+        }[];
+    }[];
+}
+/**
+ * From GraphQL `contributionsCollection { contributionCalendar { weeks { contributionDays
+ * { date contributionCount contributionLevel } } } }`. GitHub's own quartile levels pass
+ * through as 0–4, so the grid matches the profile page exactly (use the default 5 levels).
+ */
+declare function fromGitHubGraphQL(calendar: GitHubContributionCalendar): ActivityDay[];
+/** The response of the community github-contributions-api (`/v4/{user}`). */
+interface GitHubContributionsApiResponse {
+    contributions: {
+        date: string;
+        count: number;
+        level?: number;
+    }[];
+}
+/**
+ * From the community github-contributions-api (`https://github-contributions-api.jogruber.de/v4/{user}`).
+ * It is a third-party scraper of the profile page — cached for an hour and rate
+ * limited — so treat it as a convenience for demos, not a dependency.
+ */
+declare function fromGitHubContributionsApi(json: GitHubContributionsApiResponse): ActivityDay[];
+
+export { type GitHubContributionCalendar, type GitHubContributionLevel, type GitHubContributionsApiResponse, fromGitHubContributionsApi, fromGitHubGraphQL };