@sableui/react 0.11.0 → 0.12.0

package/AGENTS.md

@@ -51,10 +51,14 @@ These are short on purpose. Each links to a foundations doc with the full vocabu
 
 Pick a theme as a starting point, then override tokens on top of it. Every token a theme sets can be reset by the app on `:root` (or any subtree) after the theme CSS loads — radius, density, type scale, motion scale, accent — and components follow, because they only read tokens. The docs site's **Customize** panel does exactly this live and exports the result as CSS; paste it after your Sable imports. Retrieve the overridable set with `npx sable token --list`. When you retune a filled role (`--primary`, `--sidebar-primary`, `--highlight`, `--destructive`, `--success`, `--tone-warning`, `--tone-info`), check the label on it: `sable lint` measures the pair against the installed theme and suggests one that reads. If the pair is a deliberate brand choice, keep it with `/* design-lint-disable-next-line label-contrast -- <reason> */`. Status colours have a second token for the colour drawn on a surface — `--destructive-text`, `--success-text`, `--tone-warning-text`, `--tone-info-text` — which `text-`, `border-` and `ring-<status>` read; only `bg-<status>` reads the fill. Retune both.
 
+When a component doesn't do something you need — be a link, carry a control, take a key, offer @mentions or /commands — read `sable docs extending-a-component` before restyling or copying it: `render`, slots, controlled state and refs, `useCaretTrigger` + `CaretMenu`, and how to tell a library gap from app-owned work.
+
 ## Wire it up
 
 The machine-readable version of this section is the `consume` block in `registry.json`.
 
+**Start with `sable init`.** After `pnpm add @sableui/react`, run `pnpm exec sable init` (`npx sable init` once the package is installed — never before, when `npx sable` would fetch an unrelated package) from the app root. It runs steps 2–5 and 7 below: installs missing packages with the project's package manager, puts the CSS imports in order, adds dedupe and the Tailwind plugin to a Vite config (or a PostCSS config for Next.js), loads the fonts, mounts `IconProvider` in a Vite starter's entry, installs the agent skill, and finishes with `sable doctor`. What it cannot change safely it prints as a snippet with the file it belongs in; apply those, then run `sable doctor` again. `--dry-run` previews every change. In an app that is already wired, `sable doctor --fix` applies the same fixes to whatever doctor flags. The numbered steps are the manual route and what `init` checks against.
+
 1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed. Sable depends on no router, data or form library, and keeps whatever the project already uses: links, menus and nav items take any router's link through `render` (`render={<Link to="/inbox" />}` is TanStack Router's or React Router's `Link` alike). For a blank-slate app, the suggested stack is Vite + TypeScript with TanStack Router, TanStack Query, TanStack Form for forms with validation logic, and TanStack Table once a table outgrows `DataTable` (`sable docs tables-with-tanstack`).
 2. **Dedupe React** in the bundler (`resolve.dedupe: ["react","react-dom"]`) — Base UI must not resolve a second React, or you get an "invalid hook call" blank page.
 3. **CSS, in order:** `@import "tailwindcss";` → `@import "@sableui/react/styles.css";` → `@source "<node_modules>/@sableui/react/dist/**/*.{js,mjs}";` so Tailwind scans the package's classes. That ships every component's classes (about 32 KB gzipped); before shipping, `sable sources --write src/sable-sources.css` lists just the modules the app imports, imported in place of that `@source`, and `sable check` fails when it goes stale.
@@ -73,7 +77,8 @@ The machine-readable version of this section is the `consume` block in `registry
    npx sable pattern SettingsPage --skeleton     # composition tree, fixtures stripped
    npx sable block --list                        # section-sized blocks: cards, forms, lists
    npx sable component DataTable --props
-   npx sable search "empty state"                # across components, patterns, layout, tokens, docs
+   npx sable search "empty state"                # across components, examples, patterns, blocks, layout, tokens, docs
+   npx sable component Form --example "Server errors"   # one example a search hit names, imports included
    npx sable docs converting-an-app              # the task walkthroughs
    npx sable manifest --json                     # the whole command surface, machine-readable
    ```
@@ -150,9 +155,10 @@ package with `--root` naming the repository root (for example
 there and resolve Sable through the package.
 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
-`polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
-Cursor. `create` is a build alias. These are agent modes, not shell commands.
+Use `$sable build <idea>`, `inspire <references>`, `audit <target>`,
+`polish <target>`, or `fix <target>` in Codex; use `/sable` with the same modes in
+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

package/CHANGELOG.md

@@ -1,5 +1,175 @@
 # What's new
 
+## 0.12.0
+
+Getting to a working first component, finding the right example, moving over from shadcn, and the components that move called for: Menubar, NavigationMenu, InputGroup, ButtonGroup, CaretMenu and bottom-sheet snap points.
+
+- **New: `sable init` wires an app in one step.** Run it after `pnpm add
+  @sableui/react`. It installs what is missing with your package manager
+  (React, Tailwind and its build plugin), puts the CSS imports in order, adds
+  React dedupe and the Tailwind plugin to a Vite config (a
+  `postcss.config.mjs` for Next.js), loads Figtree and DM Mono, and wraps a
+  Vite starter's `<App />` in `IconProvider`. Then it installs the agent
+  skill and runs `sable doctor`. What it can't change safely, such as a
+  Next.js layout or an unfamiliar config, it prints as the snippet and the
+  file it belongs in. `--dry-run` shows every change first.
+- **New: `sable doctor --fix`** applies the same fixes to whatever doctor
+  flags in an app that's already set up, then checks again. A fix that
+  didn't take is reported as unverified, not done. Doctor also gains two
+  warnings: Tailwind missing from the Vite or Next.js build (`css:build`),
+  and the theme's fonts never loaded (`fonts`).
+- **`sable search` finds examples.** Every component example is searchable
+  by what it shows: `sable search "multiple selection"` or `"server errors"`.
+  A hit names its own retrieve command, `sable component Combobox --example
+  "Multiple selection"`, which prints that one example with its imports.
+  Examples are capped per component and per list, so a component name still
+  lands on the component.
+- **New: a migration guide from shadcn/ui and Radix.** `sable docs
+  migrating-from-shadcn` maps what changes everywhere (`asChild` becomes
+  `render`, values become arrays, menu rows take `onClick`,
+  `data-[state=open]:` becomes `sable-open:`), the tokens, lucide icons, and
+  every shadcn component to its Sable counterpart, or what to compose where
+  there isn't one. `converting-an-app` points to it.
+- **New lint rule: `shadcn-leftover`.** Flags imports still coming from the
+  old stack (`@radix-ui/*`, `@/components/ui`, `lucide-react`, `sonner`,
+  `vaul`, `cmdk`, `input-otp`, `next-themes`) and any `asChild` prop, which a
+  Sable trigger silently ignores. A deliberate keeper takes a reasoned disable.
+- **The agent skill has a `fix` mode.** `$sable fix <target>` (or `/sable
+  fix`) repairs one scoped defect on a short path: it reads only the
+  contracts the change touches, then runs `sable check` on the changed files
+  and looks at the affected state. It escalates to `polish`, and its full
+  finish checklist, when the change grows. Run `sable setup --agent --update`
+  to refresh installed entries.
+- **ChatComposer can send attachments without text.** Pass
+  `allowEmpty={files.length > 0}` and send enables on the files alone;
+  `onSend` receives `""`. Tie it to the pending files: a constant
+  `allowEmpty` leaves send enabled with nothing to send.
+- **ChatComposer: on a phone or tablet, Return starts a new line.** A soft
+  keyboard has no Shift+Return, so on a touch device (`pointer: coarse`) the
+  default `sendOn="enter"` now behaves as `mod-enter`: Return breaks the
+  line, the send button sends, and ⌘/Ctrl+Enter still sends from a hardware
+  keyboard. `aria-keyshortcuts` reports whichever is in effect. `footer` now
+  also takes a function of the send key in effect, so a keyboard hint can
+  stay true: `footer={({ sendOn }) => sendOn === "enter" ? "Enter to send" :
+  null}` (null removes the row). *Migration:* a fixed "Enter to send" footer
+  is wrong on touch; switch it to the function form, as ChatPanel has.
+- **Combobox documents server-backed search.** A new "Async search" example
+  and the props it uses (`filter={null}`, `onInputValueChange`,
+  `itemToStringLabel`) show how to show results a server already filtered.
+- **New: `Menubar`.** An application's row of menus (File, Edit, View) over
+  Base UI's Menubar. Each menu is an ordinary `Menu` with a `MenubarTrigger`
+  as its title. The bar is one tab stop with ←/→ between titles, and once a
+  menu is open, pointing at a neighbour opens it.
+- **New: `NavigationMenu`.** A site header's primary nav: a bar of links and
+  triggers, where a trigger opens a panel of links on hover, click or Enter.
+  One shared panel moves along the bar and resizes to each trigger's
+  content. Links take your router's link through `render` and mark the
+  current page with `active`; panel rows take a `description`. Below `md`,
+  hand the same destinations to a Sheet with a SideNav, as the docs show.
+- **Pagination can render real links.** `pageLink={(page) => <Link
+  to={`?page=${page}`} />}` makes every page control a link that crawlers
+  follow and readers can open in a new tab. The current page keeps
+  `aria-current`; the arrows at the ends stay disabled buttons.
+  `onPageChange` is optional with `pageLink`.
+- **New: `InputGroup`.** An Input with addons inside the same field: a
+  prefix or suffix ("https://", ".com"), an icon, or a borderless Button
+  such as copy or reveal. One shell, one focus ring, one error state; inside
+  a Field, the label, description and error reach the Input.
+- **OverflowMenu documents responsive actions.** Secondary actions inline
+  when the container is wide, folded into the menu when it's narrow, the
+  primary action always inline. `sable search "responsive action menu"`
+  finds it.
+- **Sheet: snap points for bottom sheets.** `<Sheet snapPoints={[0.4, 1]}>`
+  gives a bottom sheet stops between closed and fully open; a swipe moves
+  between them, and `snapPoint` / `onSnapPointChange` control the active
+  one (new `SheetSnapPoint` type). With stops the sheet shows a drag handle,
+  and the part below the screen becomes padding, so content scrolls and
+  `SheetFooter` stays visible. Other sides ignore stops and a development
+  build says so. Every bottom sheet now also rides above the on-screen
+  keyboard (measured from `visualViewport`).
+- **New: `CaretMenu` and `useCaretTrigger`, mentions and slash commands on
+  any text field.** The hook watches a Textarea, Input or ChatComposer
+  (`fieldRef`) for a trigger character at the caret (`@`, `/` at the start,
+  `#`) and reports the query. CaretMenu shows suggestions there, driven by
+  ↑/↓, Enter, Tab and Escape while focus stays in the field. The app
+  supplies the items and what choosing one does: `trigger.replace("@Sam
+  Rivera ")` inserts a mention as text, and a command runs and `replace("")`
+  clears it. The value stays a plain string; chips inside the field need a
+  rich-text editor, which Sable doesn't ship.
+- **ChatComposer: an Enter someone else handled doesn't send.** A listener
+  on `fieldRef` that handles Enter and calls `preventDefault()` owns it. It's
+  how CaretMenu picks a suggestion instead of sending, and how an app adds
+  key behaviour of its own.
+- **ChatComposer keeps focus after Stop.** Stop turns back into send in
+  place, and with an empty field that send is disabled, which dropped focus
+  to the page. Focus now moves to the field, except on touch, where it would
+  raise the keyboard unasked.
+- **Scroller eases the mouse wheel.** New `smoothWheel` (on by default): a
+  notch eases toward its target instead of jumping, on either axis, the
+  inertia a library like Lenis adds but scoped to the region. Only a mouse
+  wheel is eased: trackpads and touch keep their own momentum, keys and
+  scrollbar drags stay native, it releases at the ends so the page scrolls
+  on, a nested area that can still scroll (a code block, a textarea) keeps
+  the wheel, a region that smooths or snaps in CSS is left to the browser,
+  and anything else that moves the region (`scrollIntoView`, a scrollbar
+  drag) stops it at once. Reduced motion turns it off. New
+  `useSmoothWheel()` gives a scroll container of your own the same thing.
+- **New guide: `sable docs building-a-chat`.** Wires Sable's chat parts to
+  any streaming source: which part owns what and what stays with the app, a
+  turn's lifecycle mapped onto `busy`, `onStop`, `streaming` and `disabled`,
+  where each failure goes, announcing a turn once rather than per token, and
+  rendering model output without injecting HTML.
+- **New guide: `sable docs extending-a-component`.** What to do when a
+  component doesn't do what you need: compose with `render`, fill a slot,
+  hold the state and reach the element, add behaviour on top (mentions as
+  the worked example), change the look through tokens and presets rather
+  than overrides, patch a defect, and tell a library gap from app work.
+- **The shadcn migration guide now maps every component.** Menubar,
+  NavigationMenu, InputGroup, ButtonGroup, link Pagination and drawer snap
+  points all have counterparts.
+- **Fix: a horizontal Scroller no longer widens its container.** Its outer
+  box kept the default `min-width: auto`, so inside a grid or flex column a
+  strip of cards grew to its full length and never scrolled. It now shrinks
+  to the column and scrolls with its edge fade. The Scrolling page's own
+  example was showing exactly this, and also lacked `orientation="horizontal"`.
+- **`useCopy` takes a function.** `useCopy(() => fetch(url).then((r) =>
+  r.text()))` produces the text only on click; a pending promise goes to the
+  clipboard as a ClipboardItem so Safari still counts it as part of the click.
+  New `CopySource` type.
+- **New: `ButtonGroup`.** Buttons joined into one control, such as a split
+  button (an action beside the chevron that opens its menu) or a short run of
+  related actions. The children stay ordinary Buttons with their own variants
+  and sizes. The group squares their inner corners, collapses bordered seams
+  into one hairline and draws a seam between filled ones. Button now reads a
+  per-side radius (`--button-radius-s` / `--button-radius-e`, falling back to
+  `--button-radius`) and renders `data-variant`, which is how the group
+  does it without overriding a class.
+- **Menu rows can carry an icon and a description.** `MenuItem` takes `icon`
+  and `description`, a quieter second line saying what the action does; with
+  a description the icon sits in a small tile spanning both lines.
+- **New: `MenuLinkItem`.** A menu row that navigates: a real `<a>`, so it opens
+  in a new tab, middle-clicks and copies as a link. With `target="_blank"`
+  it adds `rel="noopener noreferrer"` and a trailing ↗.
+- **Icon contract: `arrow-up-right`.** Added for links that leave the app.
+  An app with its own icon set should map it; Reicon's set already does.
+- **sableui.com: a Copy page button on every page.** Each page with a
+  Markdown version has a split button in its header. Copy page copies the
+  page as Markdown, fetched only when you click. The menu behind the chevron
+  opens the Markdown file, starts a ChatGPT or Claude chat that reads the
+  page (Claude tries the desktop app first and falls back to claude.ai), and
+  copies the setup command (`pnpm add @sableui/react && pnpm exec
+  sable init`). The Markdown files are the same ones the site publishes at
+  `/<page>.md`; both now come from one table
+  (`apps/docs/src/markdown-twins.json`).
+- **New: `Sidebar surface="page"`.** The rail paints the page's own surface
+  and ink, with no border, instead of the theme's `--sidebar-*` set. Use it
+  when a full-width header sits above the rail: a tinted or dark rail
+  (Verdant, Meridian) starting under a page-coloured bar reads as pasted on.
+  The default, `surface="rail"`, is unchanged and still right for a
+  full-height rail. Overriding `bg-background text-foreground` on a Sidebar
+  never worked, because the rail re-points those tokens at its own;
+  use the prop instead. sableui.com's docs rail now uses it.
+
 ## 0.11.0
 
 - **New: `PropertyGroup`, a collapsible group inside a PanelSection.** The

package/DESIGN.md

@@ -469,7 +469,7 @@ Reference via `z-(--z-overlay)`, never a raw `z-[9999]`. Base UI overlays portal
 
 **Vertical gets a bar; horizontal gets a carousel.** A vertical list needs position feedback — how far through a long transcript am I — and a thin bar is the only thing that gives it. A horizontal strip does not: what a reader needs there is "there is more this way", which an **edge fade says better than a 4px rail**, and which the rail obscures by adding chrome under the content. So `Scroller` draws a bar on its vertical axis and none on its horizontal one, where its alpha-masked edges already do the work. Reach for the same split in anything strip-shaped: media rows, chip rows, tab overflow.
 
-**A horizontal region must be operable without a horizontal input.** Hiding the bar removed the last non-drag affordance on that axis, and most mice have no horizontal wheel — so `Scroller` maps a vertical wheel to sideways movement, and is focusable with arrow / Home / End / PageUp / PageDown handling. Both are on by default; the wheel mapping is `wheelScroll`, the name is `label`. The four things that make a naive wheel mapping feel broken, all handled in `useWheelToHorizontal`: it **releases at both ends** so it never traps a reader scrolling the page, it **ignores trackpad `deltaX` gestures** (`|deltaX| > |deltaY|` means the browser is already doing it, and handling `deltaY` too double-scrolls a diagonal swipe), it **ignores `shift+wheel`** (already native), and it **normalises `deltaMode`** (mice report *lines*, so the raw value moves ~3px per notch). Keyboard focus is declared rather than inherited: Chrome 128+ and Firefox make scroll regions focusable on their own, Safari does not.
+**A horizontal region must be operable without a horizontal input.** Hiding the bar removed the last non-drag affordance on that axis, and most mice have no horizontal wheel — so `Scroller` maps a vertical wheel to sideways movement, and is focusable with arrow / Home / End / PageUp / PageDown handling. Both are on by default; the wheel mapping is `wheelScroll`, the name is `label`. The four things that make a naive wheel mapping feel broken, all handled in `useSmoothWheel` (lib/use-smooth-wheel.ts): it **releases at both ends** so it never traps a reader scrolling the page, it **ignores trackpad `deltaX` gestures** (`|deltaX| > |deltaY|` means the browser is already doing it, and handling `deltaY` too double-scrolls a diagonal swipe), it **ignores `shift+wheel`** (already native), and it **normalises `deltaMode`** (mice report *lines*, so the raw value moves ~3px per notch). The same hook eases a mouse wheel on either axis (`smoothWheel`, on by default): only notches, never trackpads or touch, it gives way to a nested area that can still scroll, it leaves regions that smooth or snap in CSS to the browser, and anything else that moves the region stops the ease. Keyboard focus is declared rather than inherited: Chrome 128+ and Firefox make scroll regions focusable on their own, Safari does not.
 
 **Reveal is driven by scrolling, not by hover.** Hover is a decent proxy and a bad one for the cases that matter: a touch drag hovers nothing, and neither does a programmatic scroll — a chat auto-following a streamed reply, a jump-to-message, a restored read position — which are exactly the moments a reader needs to see where they now are. `useScrollActivity` sets `data-scrolling` on the element for ~600ms after each scroll event and `scrollbar-quiet` keys off it. Hover and `:focus-within` remain in the CSS as the no-JS baseline, so the bare utility still behaves for a consumer who never reaches for the hook. The fade honours `--motion-scale`, so reduced motion collapses it to an instant swap.
 

package/README.md

@@ -62,6 +62,17 @@ retrieval is the default. These tools do not update model weights. See
 
 > **Agents:** the machine-readable version of these steps is the `consume` block in [`registry.json`](./registry.json).
 
+**Quick start** — install, then let `sable init` do steps 2–5:
+
+```bash
+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.
+
+The steps below are what `init` does, for doing it by hand or checking its work.
+
 **1. Install:**
 
 ```bash
@@ -138,8 +149,11 @@ npx sable pattern --list                     # the eight canonical page shells
 npx sable pattern DashboardPage --skeleton   # its composition tree — 127 lines of source, 45 of structure
 npx sable block PricingCardBlock --code      # a section-sized block's source, imports included
 npx sable component Button --props
-npx sable search "date range"                # one ranked set across components, patterns, layout, tokens, docs
+npx sable search "date range"                # one ranked set across components, examples, patterns, layout, tokens, docs
+npx sable component Calendar --example Range # just the example a search hit names
+npx sable init                               # wire a new app: packages, CSS, fonts, IconProvider, agent skill, then doctor
 npx sable doctor                             # is this project wired correctly? exits 1 if not
+npx sable doctor --fix                       # apply the fixes doctor can make safely; print the rest
 npx sable docs designing-a-surface           # brief, direction, composition, interaction, adaptation
 npx sable docs developing-taste             # references, rendered directions, scoped judgment
 npx sable atlas --search "editorial culture" --contrast --limit 3 --json  # a project's own atlas, if it has one

package/bin/sable.mjs

@@ -39,6 +39,7 @@ import { skeletonize } from "../scripts/skeleton.mjs"
 import { claudeStopHook, installAgentSkill, installClaudeStopHook } from "../scripts/agent-setup.mjs"
 import { patchChecks } from "../scripts/patches.mjs"
 import { sourcesCheck } from "../scripts/sources.mjs"
+import { detectFramework, detectPackageManager, fixWiring, fontsCheck, providerSnippet, tailwindBuildCheck } from "../scripts/wiring.mjs"
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = join(HERE, "..")
@@ -139,7 +140,7 @@ const COMMANDS = [
 		summary: "One ranked result set across components, providers, patterns, blocks, layout primitives, utilities, tokens, and docs.",
 		arg: { name: "query", required: true },
 		flags: [
-			{ name: "--type", value: "component|provider|pattern|block|layout|utility|token|doc", describe: "Restrict to one kind." },
+			{ name: "--type", value: "component|provider|pattern|block|example|layout|utility|token|doc", describe: "Restrict to one kind. `example` finds a component example by what it shows (\"multiple selection\", \"server errors\")." },
 			{ name: "--limit", value: "n", describe: "Cap results. Default 20." },
 		],
 		returns: ["search"],
@@ -167,9 +168,10 @@ const COMMANDS = [
 			{ name: "--register", value: "page|workspace|either", describe: "With --list: filter by register." },
 			{ name: "--props", value: null, describe: "Props table only." },
 			{ name: "--examples", value: null, describe: "Examples only, imports included." },
+			{ name: "--example", value: "label", describe: "One example by its label (case-insensitive), imports included. Labels come from --examples or search." },
 			{ name: "--a11y", value: null, describe: "Accessibility contract only." },
 		],
-		returns: ["component.list", "component.detail", "component.props", "component.examples", "component.a11y"],
+		returns: ["component.list", "component.detail", "component.props", "component.examples", "component.example", "component.a11y"],
 	},
 	{
 		name: "pattern",
@@ -246,8 +248,23 @@ const COMMANDS = [
 		name: "doctor",
 		summary: "Check this project's Sable wiring. Exits 1 on any failure.",
 		arg: null,
-		flags: [],
-		returns: ["doctor"],
+		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." },
+			{ name: "--dry-run", value: null, describe: "Report what --fix would change without writing or installing anything." },
+			{ name: "--no-install", value: null, describe: "With --fix: print install commands instead of running them." },
+		],
+		returns: ["doctor", "doctor.fix"],
+	},
+	{
+		name: "init",
+		summary: "Wire Sable into this app in one step: install what is missing, fix what doctor flags, install the agent skill, print the provider snippet for your root, then run doctor. Vite and Next.js get every step; other setups get the packages and stylesheet, and the rest printed.",
+		arg: null,
+		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-install", value: null, describe: "Print install commands instead of running them." },
+		],
+		returns: ["init"],
 	},
 	{
 		name: "grade",
@@ -337,6 +354,7 @@ const ERROR_CODES = [
 	{ code: "ERR_PRESET_INVALID", when: "A preset is missing required metadata, semantic values, or uses unsupported tokens or CSS." },
 	{ 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_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." },
@@ -347,6 +365,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_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." },
 	{ code: "ERR_BAD_FLAG", when: "A flag value is outside its allowed set." },
@@ -630,14 +649,33 @@ function cmdSearch() {
 	if (!type || type === "doc")
 		for (const d of docSlugs())
 			pool.push({ kind: "doc", name: d.slug, summary: `${d.kind} mirror`, _s: score({ name: d.slug, text: d.kind }) })
+	if (!type || type === "example")
+		for (const c of COMPONENTS)
+			for (const e of c.examples ?? []) {
+				const s = scoreExample(c, e, { q, terms })
+				if (s > 0) pool.push({ kind: "example", name: `${c.name} › ${e.label}`, component: c.name, label: e.label, summary: `Uses ${exampleParts(e).join(", ")}.`, _s: s })
+			}
 
 	// Ties resolve in the order AGENTS.md tells an agent to resolve a need:
 	// a component first, then a pattern or primitive, then a utility, then a
 	// token. "segmented" should land on ToggleGroup before the well behind it.
-	const KIND_ORDER = ["component", "provider", "pattern", "block", "layout", "utility", "token", "doc"]
+	const KIND_ORDER = ["component", "provider", "pattern", "block", "example", "layout", "utility", "token", "doc"]
+	// A popular label ("Controlled value") exists on dozens of components, so
+	// examples are capped twice: per component, and as a share of the list, or
+	// one query would bury every component under its own examples.
+	const perComponent = new Map()
+	let examples = 0
 	const hits = pool
 		.filter((h) => h._s > 0)
 		.sort((a, b) => b._s - a._s || KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind))
+		.filter((h) => {
+			if (h.kind !== "example" || type === "example") return true
+			const n = perComponent.get(h.component) ?? 0
+			if (n >= 2 || examples >= Math.max(3, Math.ceil(limit / 3))) return false
+			perComponent.set(h.component, n + 1)
+			examples++
+			return true
+		})
 		.slice(0, limit)
 	if (!hits.length)
 		fail("ERR_NO_RESULTS", `Nothing matched "${query}".`, [
@@ -652,7 +690,10 @@ function cmdSearch() {
 	const results = hits.map(({ _s, ...h }) => ({
 		...h,
 		...(h.kind === "pattern" || h.kind === "block" ? { reference: true } : {}),
-		retrieve: `sable ${h.kind === "doc" ? "docs" : h.kind} ${h.name}`,
+		retrieve:
+			h.kind === "example"
+				? `sable component ${h.component} --example "${h.label.replace(/"/g, '\\"')}"`
+				: `sable ${h.kind === "doc" ? "docs" : h.kind} ${h.name}`,
 	}))
 	const anyReference = results.some((h) => h.reference)
 	ok("search", { query, count: results.length, results }, () =>
@@ -669,6 +710,57 @@ function cmdSearch() {
 	)
 }
 
+/** The names an example imports: the parts it composes. */
+const exampleParts = (e) =>
+	(e.imports ?? "")
+		.split(/[{}]/)[1]
+		?.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean) ?? []
+
+/** Every component and prop an example's code uses, lowercased: `<Combobox multiple items=…>` → combobox, multiple, items. */
+const exampleIdentifiers = (e) => {
+	const ids = new Set(exampleParts(e).map((p) => p.toLowerCase()))
+	for (const [, tag] of (e.code ?? "").matchAll(/<([A-Z]\w*)/g)) ids.add(tag.toLowerCase())
+	for (const [, prop] of (e.code ?? "").matchAll(/\s([a-z][A-Za-z]+)(?==|[\s/>])/g)) ids.add(prop.toLowerCase())
+	return ids
+}
+
+/**
+ * An example is found by what it shows, not by the component it belongs to. The
+ * label carries the intent ("Multiple selection", "Server errors"); the code
+ * names the parts and props it relies on; the parent component's name counts,
+ * but less than the component itself scores, so "Combobox" still lands on the
+ * component and "multiple combobox" lands on its example. An example qualifies
+ * only by its own label, or — for a phrase — by covering every term with its
+ * code: otherwise every example that renders a Button answers "button".
+ */
+function scoreExample(c, e, { q, terms }) {
+	const label = e.label.toLowerCase()
+	const ids = exampleIdentifiers(e)
+	const parent = c.name.toLowerCase()
+	const keywords = (c.keywords ?? []).map((k) => k.toLowerCase())
+	let s = terms.length > 1 && label === q ? 60 : 0
+	let labelHit = false
+	let codeHit = false
+	let covered = 0
+	for (const t of terms) {
+		const inLabel = label.includes(t)
+		const inCode = ids.has(t) ? 10 : [...ids].some((id) => id.includes(t)) ? 4 : 0
+		const inParent = parent === t ? 15 : parent.includes(t) ? 10 : keywords.includes(t) ? 5 : 0
+		s += (inLabel ? 30 : 0) + inCode + inParent
+		labelHit ||= inLabel
+		codeHit ||= inCode > 0
+		if (inLabel || inCode || inParent) covered++
+	}
+	const phrase = terms.length > 1 && covered === terms.length
+	if (!labelHit && !(phrase && codeHit)) return 0
+	// A single word is a lookup, and the component it names is the answer; a
+	// phrase is a need, and the example that covers all of it is.
+	if (terms.length === 1) return Math.round(s / 2)
+	return phrase ? s + 20 : Math.round((s * covered) / terms.length)
+}
+
 /**
  * First sentence, for one-line list rows. The abbreviation guard is not fussiness:
  * summaries in this catalog say things like "A human relative timestamp (e.g. 2h
@@ -727,6 +819,22 @@ function cmdComponent() {
 		)
 	if (flags.has("examples"))
 		return ok("component.examples", { name: c.name, examples: c.examples ?? [] }, () => renderExamples(c))
+	if (flags.has("example")) {
+		// The retrieve step for a search hit: one example, not the whole set.
+		const want = flags.get("example")
+		const labels = (c.examples ?? []).map((e) => e.label)
+		const quoted = (l) => `sable component ${c.name} --example "${l.replace(/"/g, '\\"')}"`
+		if (want === true) fail("ERR_MISSING_ARGUMENT", "--example needs a label.", labels.map(quoted))
+		const example = (c.examples ?? []).find((e) => e.label.toLowerCase() === String(want).toLowerCase())
+		if (!example) {
+			const near = nearest(String(want), labels)
+			fail("ERR_UNKNOWN_EXAMPLE", `${c.name} has no example labelled "${want}".`, [
+				...(near.length ? near : labels).map(quoted),
+				`sable component ${c.name} --examples`,
+			])
+		}
+		return ok("component.example", { name: c.name, example }, () => renderExample(example))
+	}
 	if (flags.has("a11y")) return ok("component.a11y", { name: c.name, a11y: c.a11y ?? [] }, () => (c.a11y ?? []).map(bullet).join("\n"))
 
 	const level = detailLevel("compact")
@@ -796,9 +904,11 @@ function renderUsage(c) {
 function renderExamples(c) {
 	const ex = c.examples ?? []
 	if (!ex.length) return ""
-	return `\nExamples:\n${ex
-		.map((e) => `\n  ── ${e.label}\n  ${e.imports}\n${e.code.split("\n").map((l) => `  ${l}`).join("\n")}`)
-		.join("\n")}`
+	return `\nExamples:\n${ex.map((e) => `\n${renderExample(e)}`).join("\n")}`
+}
+
+function renderExample(e) {
+	return `  ── ${e.label}\n  ${e.imports}\n${e.code.split("\n").map((l) => `  ${l}`).join("\n")}`
 }
 
 const slugify = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
@@ -1342,6 +1452,17 @@ function doctorReport() {
 			)
 	}
 
+	/* 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) {
+		const build = tailwindBuildCheck(CWD, detectFramework(CWD))
+		if (build) checks.push(build)
+	}
+	if (usesSable || sableImport.test(cssText)) {
+		const html = collectSources(/\.html$/).map((f) => f.text).join("\n")
+		checks.push(fontsCheck({ css: cssText, source: srcText, html, deps: pkg ? { ...pkg.dependencies, ...pkg.devDependencies } : {} }))
+	}
+
 	/* Local patches (sable patch): each one is re-checked against the installed
 	 * Sable, and fails when Sable changed a patched file, so an upgrade tells the
 	 * agent to re-run the repro instead of keeping or losing a fix silently. */
@@ -1354,6 +1475,7 @@ function doctorReport() {
 }
 
 function cmdDoctor() {
+	if (flags.has("fix") || flags.has("dry-run")) return cmdDoctorFix()
 	const data = doctorReport()
 	const { checks, failed } = data
 	if (JSON_OUT) {
@@ -1370,6 +1492,127 @@ function cmdDoctor() {
 	process.exit(failed ? 1 : 0)
 }
 
+/**
+ * A fix counts as applied only once doctor, run again, stops flagging its
+ * check. An edit that did not take is reported as unverified, with what doctor
+ * still says, rather than as done.
+ */
+function verifyFixes(fixes, after) {
+	for (const f of fixes) {
+		if (f.status !== "applied") continue
+		const c = after.checks.find((x) => x.name === f.check)
+		if (c && (c.status === "fail" || c.status === "warn" || (f.check === "dedupe" && c.status === "info"))) {
+			f.status = "unverified"
+			f.detail = `${f.detail} Doctor still reports: ${c.detail}`
+		}
+	}
+	return fixes
+}
+
+function fixLines(fixes, indent = "  ") {
+	const mark = { applied: "+", "would-apply": "~", manual: "!", failed: "✗", unverified: "?" }
+	const word = { applied: "", "would-apply": "", manual: "by hand: ", failed: "failed: ", unverified: "unverified: " }
+	return fixes
+		.map(
+			(f) =>
+				`${indent}${mark[f.status]} ${f.check.padEnd(14)}${word[f.status]}${f.file ? `${f.file} — ` : ""}${f.detail}\n` +
+				(f.snippet ? `${f.snippet.split("\n").map((l) => `${indent}      ${l}`).join("\n")}\n` : ""),
+		)
+		.join("")
+}
+
+function cmdDoctorFix() {
+	const dryRun = flags.has("dry-run")
+	const before = doctorReport()
+	const fixes = fixWiring({ root: CWD, pkgRoot: PKG_ROOT, report: before, framework: detectFramework(CWD), dryRun, install: !flags.has("no-install"), quiet: JSON_OUT })
+	const after = dryRun ? before : doctorReport()
+	verifyFixes(fixes, after)
+	const { failed } = after
+	if (JSON_OUT) process.stdout.write(`${JSON.stringify({ type: "doctor.fix", data: { ...after, dryRun, fixes } }, null, DENSE ? 0 : 1)}\n`)
+	else
+		process.stdout.write(
+			[
+				fixes.length ? `${dryRun ? "Would fix (dry run, nothing written):" : "Fixes:"}\n${fixLines(fixes)}` : "Nothing to fix.\n",
+				`${dryRun ? "Now:" : "After:"}\n${doctorLines(after.checks)}`,
+				failed ? `[sable doctor] ✗ ${failed} failure(s)${dryRun ? "" : " left; the steps marked ! need you"}.\n` : "[sable doctor] ✓ wiring holds.\n",
+			].join("\n"),
+		)
+	logInvocation(failed ? 1 : 0)
+	process.exit(failed ? 1 : 0)
+}
+
+/* ── init ───────────────────────────────────────────────────────────────────── */
+
+/**
+ * The install recipe, run: doctor --fix, the agent skill, and the provider the
+ * 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() {
+	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")
+	const framework = detectFramework(CWD)
+	const packageManager = detectPackageManager(CWD)
+	const before = doctorReport()
+	const fixes = fixWiring({ root: CWD, pkgRoot: PKG_ROOT, report: before, framework, dryRun, install: !flags.has("no-install"), quiet: JSON_OUT })
+
+	let agent
+	if (flags.has("no-agent")) agent = { status: "skipped" }
+	else
+		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 }
+		} catch (error) {
+			agent = { status: "manual", detail: error.message, fix: "sable setup --agent --dry-run" }
+		}
+
+	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 }
+
+	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(", ")}.`,
+			skipped: () => "Agent skill: skipped (--no-agent).",
+			manual: () => `Agent skill: not installed — ${agent.detail}\n  → ${agent.fix}`,
+		}[agent.status]()
+		const iconsFix = fixes.find((f) => f.check === "icons")
+		const providerText = mounted
+			? "Providers: <IconProvider> is mounted. MotionProvider and SableThemeProvider are optional: sable provider --list."
+			: iconsFix?.status === "would-apply"
+				? `Providers: <IconProvider> would be mounted in ${iconsFix.file}.`
+				: iconsFix?.status === "manual"
+					? "Providers: mount IconProvider as shown under icons above."
+					: [`Providers — mount IconProvider once, in ${providers.file}${providers.then ? `, then ${providers.then}` : ""}:`, ...providers.code.split("\n").map((l) => `    ${l}`)].join("\n")
+		process.stdout.write(
+			[
+				`sable init — ${framework.label}, ${packageManager}${dryRun ? " (dry run: nothing written or installed)" : ""}`,
+				...(framework.id === "unknown" ? ["Not Vite or Next.js: init installs the packages and wires the stylesheet it finds; the bundler and provider steps are printed for you."] : []),
+				"",
+				fixes.length ? `${dryRun ? "Would fix:" : "Fixes:"}\n${fixLines(fixes)}` : "Nothing to fix.\n",
+				agentText,
+				"",
+				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"}`,
+				"",
+			].join("\n"),
+		)
+	}
+	logInvocation(after.failed ? 1 : 0)
+	process.exit(after.failed ? 1 : 0)
+}
+
 function doctorLines(checks, indent = "  ") {
 	const mark = { pass: "✓", warn: "!", fail: "✗", info: "·" }
 	return checks
@@ -1407,7 +1650,7 @@ function collectSources(match, limit = 4000) {
 
 
 function readConfigs() {
-	return ["vite.config.ts", "vite.config.js", "next.config.js", "next.config.mjs", "webpack.config.js"]
+	return ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs", "next.config.ts", "next.config.js", "next.config.mjs", "webpack.config.js"]
 		.map((f) => (existsSync(join(CWD, f)) ? readFileSync(join(CWD, f), "utf8") : ""))
 		.join("\n")
 }
@@ -1698,6 +1941,7 @@ const HANDLERS = {
 	utility: cmdUtility,
 	docs: cmdDocs,
 	doctor: cmdDoctor,
+	init: cmdInit,
 	grade: cmdGrade,
 	learn: cmdLearn,
 	atlas: () => cmdDesignTool("design-atlas.mjs"),