diff --git a/.agents/03-stack-and-commands.md b/.agents/03-stack-and-commands.md
index ecec5ba0..6b48e0f8 100644
--- a/.agents/03-stack-and-commands.md
+++ b/.agents/03-stack-and-commands.md
@@ -43,7 +43,7 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 
 ## Generated artifacts under `src/`
 
-Ahead-of-time build artifacts that live under `src/` - the shadow-root stylesheets in `packages/hub-ui/src/client/.generated/` and `packages/json-render-ui/src/.generated/` - are **generated, not committed** (`.generated` is gitignored). Each owning package builds its own with `pnpm run build:css`; three things guarantee the file is on disk before anything imports it: the root `postinstall` runs `turbo run build:css`, the Turbo `typecheck` task depends on both `build:css` tasks, and each package's `build` script chains `build:css` first. A new generated-under-`src` artifact MUST follow the same shape - its own build script, declared `outputs` in `turbo.json`, and a `typecheck` dependency - and MUST NOT be checked in: a minified single-line blob conflicts on every concurrent edit.
+Ahead-of-time build artifacts that live under `src/` - the shadow-root stylesheets in `packages/hub-ui/src/client/.generated/`, `packages/hub-ui-onboard/src/client/.generated/` and `packages/json-render-ui/src/.generated/` - are **generated, not committed** (`.generated` is gitignored). Each owning package builds its own with `pnpm run build:css`; three things guarantee the file is on disk before anything imports it: the root `postinstall` runs `turbo run build:css`, the Turbo `typecheck` task depends on every `build:css` task, and each package's `build` script chains `build:css` first. A new generated-under-`src` artifact MUST follow the same shape - its own build script, declared `outputs` in `turbo.json`, and a `typecheck` dependency - and MUST NOT be checked in: a minified single-line blob conflicts on every concurrent edit.
 
 ## `starter/`
 
diff --git a/.agents/06-design-system.md b/.agents/06-design-system.md
index 2870a002..2ddc30ab 100644
--- a/.agents/06-design-system.md
+++ b/.agents/06-design-system.md
@@ -12,9 +12,9 @@ Each consumer's `uno.config.ts` composes the same stack: `presetAnthonyDesign({
 
 ## Wind4 by default, Wind3 for shadow roots
 
-Ordinary surfaces (plugins served in iframes, examples in the page) use `presetWind4()`. A surface whose stylesheet is injected into a **shadow root** (`@devframes/hub-ui`'s dock custom element, `@devframes/json-render-ui`'s renderer module) MUST build on **`presetWind3()`** instead - via `createDesignConfig({ base: presetWind3() })`, or `presetWind3()` directly. Wind4 keeps `@antfu/design`'s theme in a document `:root {}` block and registers its `--un-*` custom properties with `@property { inherits: false }`, neither of which reaches a shadow tree - its `color-mix(var(--colors-*))` semantic utilities (`bg-base`, `color-base`, …) resolve to nothing inside a shadow root. Wind3 bakes the same shortcuts to concrete `rgb()` + `.dark` variants, self-contained in the shadow tree.
+Ordinary surfaces (plugins served in iframes, examples in the page) use `presetWind4()`. A surface whose stylesheet is injected into a **shadow root** (`@devframes/hub-ui`'s dock custom element, `@devframes/json-render-ui`'s renderer module, `@devframes/hub-ui-onboard`'s floating button) MUST build on **`presetWind3()`** instead - via `createDesignConfig({ base: presetWind3() })`, or `presetWind3()` directly. Wind4 keeps `@antfu/design`'s theme in a document `:root {}` block and registers its `--un-*` custom properties with `@property { inherits: false }`, neither of which reaches a shadow tree - its `color-mix(var(--colors-*))` semantic utilities (`bg-base`, `color-base`, …) resolve to nothing inside a shadow root. Wind3 bakes the same shortcuts to concrete `rgb()` + `.dark` variants, self-contained in the shadow tree.
 
-Two shadow-root gotchas the ahead-of-time CSS builder MUST compensate for (both handled in the shared `design/build-shadow-css.ts` pipeline, consumed by `packages/{hub-ui,json-render-ui}/scripts/build-css.ts`; the Vite `unocss/vite` path for standalone SPAs and Storybook is not affected):
+Two shadow-root gotchas the ahead-of-time CSS builder MUST compensate for (both handled in the shared `design/build-shadow-css.ts` pipeline, consumed by `packages/{hub-ui,hub-ui-onboard,json-render-ui}/scripts/build-css.ts`; a surface that renders none of `@antfu/design`'s Vue components passes `scanDesignComponents: false` to keep its stylesheet small; the Vite `unocss/vite` path for standalone SPAs and Storybook is not affected):
 
 - **Plain-vs-variant shortcut drop.** When a semantic shortcut also appears **variant-prefixed** in the scanned sources (e.g. `@antfu/design`'s Tabs emits `data-[state=active]:bg-base`), a single-pass `generate(tokens)` drops the *plain* `.bg-base` / `.color-base` rule - so emit the surface tokens (`design/uno.config.ts`'s exported `shadowSurfaceSafelist`) in a **dedicated `generate()` pass** and append them.
 - **`--un-*` collision with a Wind4 host.** `@property` registrations are document-global, so a host page built on Wind4 registers `--un-bg-opacity` / `--un-border-opacity` / `--un-text-opacity` as `@property { syntax: '<percentage>' }` for the whole document, including our shadow tree - which invalidates the *unitless* values Wind3 writes (`--un-border-opacity: 0.13`) and collapses the dependent `rgb(… / var(--un-*))` color (a visibly wrong border/background). Rename every `--un-` in the shadow stylesheet to a private prefix with `design/uno.config.ts`'s exported `namespaceShadowCssVars()` so it's immune to whatever the host registered.
diff --git a/.agents/08-diagnostics.md b/.agents/08-diagnostics.md
index 8dcbfb1d..5986e205 100644
--- a/.agents/08-diagnostics.md
+++ b/.agents/08-diagnostics.md
@@ -2,7 +2,7 @@
 
 All node-side warnings and errors use structured diagnostics via [`nostics`](https://www.npmjs.com/package/nostics). Node-side code MUST NOT use raw `console.warn`, `console.error`, or `throw new Error` with ad-hoc messages - always define a coded diagnostic. Browser-only code is out of scope and keeps using `console.*` / `throw`.
 
-Import `defineDiagnostics` (and `Diagnostic` for `instanceof` checks) from `devframe/utils/nostics`, never from `nostics` directly - it pre-wires devframe's ANSI console reporter, so a plugin's `diagnostics.ts` never builds its own reporter (`colors`, `ansiFormatter`) or depends on `nostics` itself.
+Import `defineDiagnostics` (and `Diagnostic` for `instanceof` checks) from `devframe/utils/nostics`, never from `nostics` directly - it pre-wires devframe's ANSI console reporter, so a plugin's `diagnostics.ts` never builds its own reporter (`colors`, `ansiFormatter`) or depends on `nostics` itself. One exception: `@devframes/hub-ui-onboard` MUST stay free of `devframe` (a host ships it while devframe is not installed), so it imports `defineDiagnostics` and `createConsoleReporter` from `nostics` directly.
 
 ## Code ranges
 
@@ -16,6 +16,7 @@ Prefix: **`DF`**. Codes are sequential 4-digit numbers (e.g. `DF0033`) - check t
   - `DF83xx` - messages
   - `DF84xx` - commands
   - `DF85xx` - built-in RPC commands
+- `DF90xx` - `@devframes/hub-ui-onboard` (install, state file, hand-off)
 
 ## Adding a new error
 
diff --git a/alias.ts b/alias.ts
index 6940f8e2..b128d0ad 100644
--- a/alias.ts
+++ b/alias.ts
@@ -61,6 +61,7 @@ export const alias = {
   '@devframes/hub/types': r('hub/src/types/index.ts'),
   '@devframes/hub': r('hub/src/index.ts'),
   '@devframes/hub-ui': r('hub-ui/src/index.ts'),
+  '@devframes/hub-ui-onboard': r('hub-ui-onboard/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt/single': r('nuxt/src/single.ts'),
   '@devframes/nuxt/hub/client': r('nuxt/src/hub-client.ts'),
diff --git a/design/build-shadow-css.ts b/design/build-shadow-css.ts
index c68f8608..686056ef 100644
--- a/design/build-shadow-css.ts
+++ b/design/build-shadow-css.ts
@@ -42,6 +42,12 @@ export interface BuildShadowCssOptions {
    * shadow trees on the same host page never collide.
    */
   varPrefix: string
+  /**
+   * Also scan `@antfu/design`'s Vue components so the classes they use ship
+   * in the stylesheet. Default `true`; a surface that renders none of those
+   * components turns it off to keep the stylesheet small.
+   */
+  scanDesignComponents?: boolean
 }
 
 export interface BuildShadowCssResult {
@@ -63,7 +69,7 @@ export interface BuildShadowCssResult {
  * exempt from the `no-console` lint rule) prints its own summary line.
  */
 export async function buildShadowCss(options: BuildShadowCssOptions): Promise<BuildShadowCssResult> {
-  const { srcDir, globs, config, primaryRampPath, userStylePath, varPrefix } = options
+  const { srcDir, globs, config, primaryRampPath, userStylePath, varPrefix, scanDesignComponents = true } = options
   const generatedCss = join(srcDir, '.generated/css.ts')
 
   const require = createRequire(import.meta.url)
@@ -81,11 +87,13 @@ export async function buildShadowCss(options: BuildShadowCssOptions): Promise<Bu
   // package's component sources too so those classes ship in the injected
   // CSS.
   const designComponentsDir = join(require.resolve('@antfu/design/package.json'), '..', 'components')
-  const designFiles = await glob('**/*.vue', {
-    cwd: designComponentsDir,
-    absolute: true,
-    ignore: IGNORE,
-  })
+  const designFiles = scanDesignComponents
+    ? await glob('**/*.vue', {
+        cwd: designComponentsDir,
+        absolute: true,
+        ignore: IGNORE,
+      })
+    : []
 
   const generator = await createGenerator(config)
 
diff --git a/docs/content/1.guide/18.hub-initiate.md b/docs/content/1.guide/18.hub-initiate.md
index f5d2a86f..e84001d0 100644
--- a/docs/content/1.guide/18.hub-initiate.md
+++ b/docs/content/1.guide/18.hub-initiate.md
@@ -63,6 +63,10 @@ interface DevframeHubUi {
 
 To add a language, add its tag and native name to `packages/hub-ui/src/locales.ts`, translate a copy of `packages/hub-ui/src/client/i18n/locales/en.json` under that tag, and register the file in the `messages` map in `packages/hub-ui/src/client/i18n/index.ts`. The i18n test fails on a missing key or a changed `{slot}`.
 
+## Onboarding without the hub installed
+
+A host that wants DevTools as an opt-in install ships `@devframes/hub-ui-onboard` instead of the hub: a 20 kB floating button at the same `<base>embedded.js` URL, an Install action that runs the project's package manager, and an `onInstalled` hook that hands `base` to the real hub in the same process. See [Opt-in DevTools with Onboarding](/guide/hub-ui-onboard).
+
 ## Renderer modules
 
 A dock type's renderer (e.g. [JSON-Render](/guide/json-render)) composes via `initHub({ renderers })`. Each registration `{ type, file, importName? }` (`file` = a prebuilt ES module exporting a `DockRenderer`) is served at `<base>__renderers/<type>.mjs` and published into the `devframe:dock-renderers` manifest; client runtimes import it lazily on first mount:
diff --git a/docs/content/1.guide/23.hub-ui-onboard.md b/docs/content/1.guide/23.hub-ui-onboard.md
new file mode 100644
index 00000000..f3fc9a9a
--- /dev/null
+++ b/docs/content/1.guide/23.hub-ui-onboard.md
@@ -0,0 +1,187 @@
+---
+title: 'Opt-in DevTools with Onboarding'
+navigation:
+  icon: i-lucide-download
+description: '@devframes/hub-ui-onboard lets a host ship a 20 kB floating button instead of the hub, install the hub on demand, and hand the hub base to it without a restart.'
+---
+
+`@devframes/hub-ui-onboard` lets a host ship a 20 kB floating button instead of the hub, install the hub on demand, and hand the hub base to it in the same process.
+
+## Why
+
+A hub UI provider, its Vue runtime, and the devframes it mounts add tens of megabytes to a framework's install size. A host that wants DevTools as an opt-in can move those packages to optional peers and ship only this package: one browser file, a handful of routes, and three small runtime dependencies (a package-manager detector, a process runner, the diagnostics library). The user still discovers DevTools through the usual floating button; the first click installs them.
+
+## What the user sees
+
+The button sits at the bottom left, dimmed until hovered. It opens a panel with the product name and logo, one sentence, the exact command the install will run (for example `pnpm add -D @nuxt/devtools`), and three actions:
+
+- **Install** runs the command in the project. The panel shows progress, then either the real dock replaces the button in place, or the panel asks for a restart.
+- **Hide for now** removes the button for the current browser tab.
+- **Disable entirely** writes a state file so the host stops injecting the button on every later start.
+
+The panel follows the shared design tokens, the host's `primaryColor`, and the user's hub color scheme, so the swap to the real dock looks like one product.
+
+## Create the onboarding
+
+```ts
+import { createOnboarding } from '@devframes/hub-ui-onboard'
+
+const onboarding = createOnboarding({
+  packages: ['@devframes/hub', '@devframes/hub-ui'],
+  branding: { productName: 'My DevTools', logo: '/logo.svg', primaryColor: '#646cff' },
+})
+```
+
+`createOnboarding()` returns four things:
+
+- `handler(request)`: a web-standard `Request => Response` handler for every path under `base` (default `/__devframes/`).
+- `nodeMiddleware(req, res, next)`: the same handler as Connect middleware for Vite, Express, Fastify with `@fastify/middie`, or a plain `node:http` server. It calls `next()` for paths outside `base`.
+- `scriptSrc`: `<base>embedded.js`, the URL to inject as `<script type="module">`.
+- `disabled` and `installed`: what the host needs to decide whether to inject the script at all (below).
+
+`packages` are package specs as the package manager accepts them. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn`, `bun`, `deno`), `dev: true` adds `-D`, and `cwd` (default `process.cwd()`) is the project that receives the dependency. In a workspace, point `cwd` at the package that runs the dev server. The packages are fixed at creation, and a `POST` from another origin is refused.
+
+## Hand the base to the hub
+
+Return a handler from `onInstalled` and the hub takes over `base` in the same process. The button then loads the real `embedded.js` from that handler and removes itself.
+
+```ts
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const require = createRequire(join(cwd, 'package.json'))
+const load = <T>(id: string): Promise<T> => import(pathToFileURL(require.resolve(id)).href)
+
+const onboarding = createOnboarding({
+  cwd,
+  packages: ['@devframes/hub', '@devframes/hub-ui'],
+  async onInstalled() {
+    const [{ initHub }, { createUi }] = await Promise.all([
+      load<typeof import('@devframes/hub/initiate')>('@devframes/hub/initiate'),
+      load<typeof import('@devframes/hub-ui')>('@devframes/hub-ui'),
+    ])
+    const hub = initHub({ base: '/__devframes/', cwd, server: httpServer, ui: createUi(), devframes: [] })
+    return hub.handler
+  },
+})
+```
+
+Resolve the new packages from the project's `package.json`, as above. Under pnpm they are dependencies of the project, so a bare `import('@devframes/hub')` from the host's own file fails. Pass the live `node:http` server so the hub attaches its WebSocket to it; `initHub` accepts a server after it started listening.
+
+`onInstalled` is also how the onboarding short-circuits. When every named package is already in `node_modules` at creation, `onboarding.installed` is `true`, `onInstalled` runs on the first request, and the user never sees the button. A host can therefore mount the onboarding unconditionally during development: it serves the hub when the packages exist and the button when they are missing.
+
+Without `onInstalled`, or when it returns nothing, the panel reports the install and asks for a restart. The next start finds the packages installed.
+
+## When to inject the button
+
+Inject `scriptSrc` only when `onboarding.disabled` is `false`. The user set that flag with "Disable entirely"; it lives in `<stateDir>/hub-ui-onboard.json`, default `<cwd>/node_modules/.devframe`.
+
+Mount the onboarding only when the user did not set the host's own devtools option. An explicit `devtools: true` means the host installs or requires DevTools itself; an explicit `devtools: false` means no button. The onboarding covers the unset case, and a user who disabled it from the panel turns it back on by setting the option.
+
+## Hosts
+
+### Vite
+
+A plugin mounts the middleware and injects the tag. `examples/hub-onboard-vite` is the complete version with the hub hand-off.
+
+```ts [vite.config.ts]
+import type { Plugin } from 'vite'
+import { createOnboarding } from '@devframes/hub-ui-onboard'
+
+function hubOnboarding(): Plugin {
+  const onboarding = createOnboarding({ packages: ['@devframes/hub', '@devframes/hub-ui'] })
+  return {
+    name: 'hub-onboarding',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(onboarding.nodeMiddleware)
+    },
+    transformIndexHtml() {
+      return onboarding.disabled
+        ? []
+        : [{ tag: 'script', attrs: { type: 'module', src: onboarding.scriptSrc }, injectTo: 'body' }]
+    },
+  }
+}
+```
+
+### Nuxt
+
+Nuxt runs Vite, so a module reuses the plugin above and adds the tag to `app.head`. Gate it on the dev server, and skip it when the user set your own devtools option.
+
+```ts [modules/devtools-onboarding.ts]
+import { createOnboarding } from '@devframes/hub-ui-onboard'
+import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(_, nuxt) {
+    if (!nuxt.options.dev)
+      return
+    const onboarding = createOnboarding({
+      cwd: nuxt.options.rootDir,
+      packages: ['@nuxt/devtools'],
+      branding: { productName: 'Nuxt DevTools', primaryColor: '#00dc82' },
+    })
+    addVitePlugin({
+      name: 'devtools-onboarding',
+      configureServer: server => server.middlewares.use(onboarding.nodeMiddleware),
+    })
+    if (!onboarding.disabled)
+      (nuxt.options.app.head.script ??= []).push({ type: 'module', src: onboarding.scriptSrc })
+  },
+})
+```
+
+### Next.js
+
+A route handler forwards `Request` objects, and the root layout renders the tag.
+
+```ts [app/__devframes/[[...path]]/route.ts]
+import { onboarding } from '../../../devtools-onboarding'
+
+export const GET = (request: Request) => onboarding.handler(request)
+export const POST = (request: Request) => onboarding.handler(request)
+```
+
+```tsx [app/layout.tsx]
+import { onboarding } from '../devtools-onboarding'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        {process.env.NODE_ENV === 'development' && !onboarding.disabled && (
+          <script type="module" src={onboarding.scriptSrc} />
+        )}
+      </body>
+    </html>
+  )
+}
+```
+
+A Next route handler cannot accept a WebSocket upgrade, so a hub started from `onInstalled` uses a side-car socket (`ws: { sidecar: true }`); see [Next](/frameworks/next#mounting-a-hub).
+
+### Any Node server
+
+```ts
+import { createServer } from 'node:http'
+
+createServer((req, res) => {
+  onboarding.nodeMiddleware(req, res, () => {
+    res.statusCode = 404
+    res.end()
+  })
+}).listen(3000)
+```
+
+Frameworks with a `Request => Response` surface (Hono, Nitro, Deno) mount `onboarding.handler` under `base` instead.
+
+## Strings and branding
+
+`branding` takes `productName`, `logo` (one URL or `{ light, dark }`) and `primaryColor`, the same three fields hub-ui's `DevframeBranding` starts with. Every string in the panel derives from `productName` and is overridable through `messages`; the keys are listed in the [Hub API reference](/references/hub-api#onboarding-options-and-routes).
+
+## Errors
+
+The Node side reports through `DF9000` to `DF9004`. An install failure or a throwing `onInstalled` also reaches the panel as `{ state: 'error', error: { code, message } }`, with a Retry button. See the [error reference](/errors).
diff --git a/docs/content/1.guide/index.md b/docs/content/1.guide/index.md
index 5ceb6494..eec8a329 100644
--- a/docs/content/1.guide/index.md
+++ b/docs/content/1.guide/index.md
@@ -178,4 +178,5 @@ The CLI adapter serves the SPA at `/`; embedded in a host framework (`vite`, `em
 - [The Standard Handler](/adapters/initiate): mount into any host framework
 - [Adapters](/adapters): convenience entry points
 - [Hub](/guide/hub): compose many devframes
+- [Opt-in DevTools with Onboarding](/guide/hub-ui-onboard): ship a 20 kB button and install the hub on demand
 - [Pluggable, Extensible, and Playful DevTools](/posts/pluggable-extensible-playful-devtools): the vision and story behind Devframe
diff --git a/docs/content/3.frameworks/index.md b/docs/content/3.frameworks/index.md
index bd0764a4..2adffbbc 100644
--- a/docs/content/3.frameworks/index.md
+++ b/docs/content/3.frameworks/index.md
@@ -29,3 +29,5 @@ For framework-neutral CLI/build/embedded outputs, use the [adapters](/adapters)
 Each `hub` scope wraps [`initHub`](/guide/hub-initiate) and defaults the UI to [`@devframes/hub-ui`](/guide/build-your-own-hub-ui)'s `createUi()` (`ui` to override, `ui: false` for headless). Per tool: **[Vite](/frameworks/vite#mounting-a-hub)**, **[Nuxt](/frameworks/nuxt#mounting-a-hub)**, **[Next](/frameworks/next#mounting-a-hub)**.
 
 `@devframes/vite/hub` and `@devframes/nuxt/hub` recommend the native hub UI providers ([Vite DevTools](https://devtools.vite.dev), [Nuxt DevTools](https://devtools.nuxt.com)) once (silence with `{ quiet: true }`). Next has none, so `@devframes/next/hub` stays quiet.
+
+A framework that wants DevTools as an opt-in install ships [`@devframes/hub-ui-onboard`](/guide/hub-ui-onboard) instead of the hub and lets the user install it from a floating button.
diff --git a/docs/content/6.errors/DF9000.md b/docs/content/6.errors/DF9000.md
new file mode 100644
index 00000000..409c1a39
--- /dev/null
+++ b/docs/content/6.errors/DF9000.md
@@ -0,0 +1,28 @@
+---
+title: 'DF9000: No Packages to Install'
+description: '`createOnboarding()` received no packages to install.'
+---
+
+## Message
+
+> `createOnboarding()` received no packages to install.
+
+## Cause
+
+The Install button runs one package-manager command built from `packages`. With an empty list there is nothing for it to do.
+
+## Example
+
+```ts
+import { createOnboarding } from '@devframes/hub-ui-onboard'
+
+createOnboarding({ packages: [] }) // ✗ throws DF9000
+```
+
+## Fix
+
+Pass at least one package spec, for example `packages: ['@nuxt/devtools']`.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `createOnboarding` throws this before it reads any other option.
diff --git a/docs/content/6.errors/DF9001.md b/docs/content/6.errors/DF9001.md
new file mode 100644
index 00000000..f9f827a9
--- /dev/null
+++ b/docs/content/6.errors/DF9001.md
@@ -0,0 +1,20 @@
+---
+title: 'DF9001: Install Command Failed'
+description: 'The package manager exited with a non-zero code.'
+---
+
+## Message
+
+> `{command}` exited with code `{exitCode}`.
+
+## Cause
+
+The Install button ran the project's package manager (`npm`, `pnpm`, `yarn`, `bun` or `deno`, detected from the lockfile) and it failed. The last lines of its error output follow the message. Common reasons: no network, a package name that does not exist, or a package manager that is not on `PATH`.
+
+## Fix
+
+Run the command shown in the panel in a terminal to see the full output. Fix the cause, then click Retry. The panel keeps the error until the next attempt.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/install.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/install.ts): `runInstall` throws this when the process exits with a non-zero code. The status route reports it as `{ state: 'error', error: { code, message } }`.
diff --git a/docs/content/6.errors/DF9002.md b/docs/content/6.errors/DF9002.md
new file mode 100644
index 00000000..c459fe67
--- /dev/null
+++ b/docs/content/6.errors/DF9002.md
@@ -0,0 +1,20 @@
+---
+title: 'DF9002: Installed Package Not Found'
+description: 'The install finished, but a package is not in the project node_modules.'
+---
+
+## Message
+
+> The install finished, but "`{name}`" is not in `{cwd}`/node_modules.
+
+## Cause
+
+The package manager exited with code 0, but `<cwd>/node_modules/<name>` does not exist. This happens when `cwd` points at a directory other than the one the package manager installed into, for example the workspace root instead of the package that runs the dev server.
+
+## Fix
+
+Set `cwd` to the project that receives the dependency. In a workspace, that is the package whose dev server mounts the onboarding handler.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/install.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/install.ts): `runInstall` checks each named package after the command succeeds. Path, URL and alias specs are not checked, because their installed name is not in the spec.
diff --git a/docs/content/6.errors/DF9003.md b/docs/content/6.errors/DF9003.md
new file mode 100644
index 00000000..72058a09
--- /dev/null
+++ b/docs/content/6.errors/DF9003.md
@@ -0,0 +1,20 @@
+---
+title: 'DF9003: onInstalled Threw'
+description: '`onInstalled` threw after the packages were installed: {reason}'
+---
+
+## Message
+
+> `onInstalled` threw after the packages were installed: `{reason}`
+
+## Cause
+
+The packages are installed. The host's `onInstalled` callback, which usually imports the new packages and starts the hub, threw. `{reason}` is its message; the original error is attached as `cause`.
+
+## Fix
+
+Read the `cause`. A frequent one is a module that cannot be resolved: resolve the new packages from the project root (`createRequire(join(cwd, 'package.json'))`), not from the config file, because under pnpm they are only reachable from there. A restart of the dev server also loads the installed packages.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `install()` reports this and sets `state: 'error'` when `onInstalled` rejects.
diff --git a/docs/content/6.errors/DF9004.md b/docs/content/6.errors/DF9004.md
new file mode 100644
index 00000000..47f6bdb1
--- /dev/null
+++ b/docs/content/6.errors/DF9004.md
@@ -0,0 +1,20 @@
+---
+title: 'DF9004: Onboarding State File Unreadable'
+description: 'The onboarding state file could not be read or written.'
+---
+
+## Message
+
+> The onboarding state file `{file}` could not be read or written.
+
+## Cause
+
+`createOnboarding()` reads `<stateDir>/hub-ui-onboard.json` at start to learn whether the user disabled DevTools, and the Disable button writes it. The file exists but is not valid JSON, or the directory is not writable.
+
+## Fix
+
+Delete the file if it is corrupt. If the directory is read-only, pass another `stateDir`. The default is `<cwd>/node_modules/.devframe`.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `readDisabled` warns and treats the state as not disabled; `disable()` answers the request with status 500 and this code.
diff --git a/docs/content/8.references/1.terms.md b/docs/content/8.references/1.terms.md
index d53d5703..dfbc704d 100644
--- a/docs/content/8.references/1.terms.md
+++ b/docs/content/8.references/1.terms.md
@@ -20,6 +20,7 @@ Every concept in these docs has exactly one name. This page fixes that vocabular
 | **opt-in package** | A capability shipped as its own package and added when needed. | `@devframes/json-render` |
 | **hub** | The composition layer that puts many devframes behind one handler; *a hub* is one `initHub()` instance. | `@devframes/hub`, `initHub()` |
 | **hub UI provider** | A hub UI implementation: the node-side `ui` slot plus the browser-side context contract. `@devframes/hub-ui` is the reference hub UI provider. | `initHub({ ui })` |
+| **onboarding** | The stand-in a host ships when no hub UI provider is installed: a floating button that installs the configured packages and hands the hub base to the real hub. `@devframes/hub-ui-onboard`. Not a dock entry; the `launcher` dock entry type is unrelated. | `createOnboarding()` |
 
 ## Node side
 
diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md
index 8acd106f..55f084a9 100644
--- a/docs/content/8.references/6.hub-api.md
+++ b/docs/content/8.references/6.hub-api.md
@@ -84,6 +84,37 @@ What `initHub()` serves under its `base`: [The namespace](/guide/hub-initiate#th
 | `__client-imports.js` | dock client-script import map for hub UI providers |
 | `__mcp` | aggregate MCP endpoint over the tool registry (`mcp: 'auto'` default: mounted once agent tools exist) |
 
+## Onboarding options and routes
+
+What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [Opt-in DevTools with Onboarding](/guide/hub-ui-onboard).
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `packages` | required | Package specs the Install button adds |
+| `base` | `/__devframes/` | Mount base, shared with the hub that takes over later |
+| `cwd` | `process.cwd()` | Project that receives the dependency and whose lockfile picks the package manager |
+| `stateDir` | `<cwd>/node_modules/.devframe` | Directory of the `hub-ui-onboard.json` state file |
+| `dev` | `true` | Install as a devDependency |
+| `branding` | `{}` | `productName` (default `Devframes`), `logo` (URL or `{ light, dark }`), `primaryColor` |
+| `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `hide`, `disable`, `installing`, `restart`, `retry` |
+| `onInstalled` | none | Runs after a verified install, or on the first request when the packages already exist; a returned handler takes over `base` |
+
+| Route | Serves |
+| --- | --- |
+| `GET <base>embedded.js` | the floating button, a self-contained ES module |
+| `GET <base>__onboard/status` | `{ state, command, branding, messages, error? }` |
+| `POST <base>__onboard/install` | starts the install (`202`), same-origin only |
+| `POST <base>__onboard/disable` | writes the state file (`204`), same-origin only |
+
+| `state` | Meaning |
+| --- | --- |
+| `idle` | nothing installed yet; the panel offers Install |
+| `installing` | the package manager is running; the button polls once a second |
+| `installed` | installed, no hub handler to hand off to; the panel asks for a restart |
+| `ready` | `onInstalled` returned a handler; the button loads the real `embedded.js` and removes itself |
+| `error` | the install or `onInstalled` failed; `error.code` is a `DF90xx` diagnostic |
+| `disabled` | the user chose Disable entirely; the button renders nothing |
+
 ## `buildHub` options
 
 The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/hub-initiate#static-builds). `devframes`, `services`, `rpcDeclarations`, `configure`, `ui`, `renderers`, `name`, `version`, `cwd`, and `getStorageDir` carry the same contracts as their `initHub` counterparts.
diff --git a/docs/content/8.references/index.md b/docs/content/8.references/index.md
index bc01b8fa..ceedcd40 100644
--- a/docs/content/8.references/index.md
+++ b/docs/content/8.references/index.md
@@ -12,7 +12,7 @@ Lookup pages the guides link into:
 - [Events Reference](/references/events): every event, broadcast, shared-state key, and channel name, by direction and reach.
 - [Node-Side API](/references/node-api): `DevframeDefinition` fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the `ctx.services` host and wire-service fields, diagnostics prefixes, and the auth surface.
 - [Browser-Side API](/references/browser-api): `connectDevframe` options, RPC client events, connection statuses, and in-page channel error codes.
-- [Hub API](/references/hub-api): hub subsystems, launcher fields, duplication strategies, dock categories, the hub UI protocol, the namespace routes, the client runtime, the client context, and dock entry types.
+- [Hub API](/references/hub-api): hub subsystems, launcher fields, duplication strategies, dock categories, the hub UI protocol, the namespace routes, the onboarding options and routes, the client runtime, the client context, and dock entry types.
 - [Utilities](/references/utilities): the small, stable helpers under `devframe/utils/*`, bundled into `devframe`.
 - [Interactive Auth](/references/interactive-auth): the OTP auth recipe: handshake, resolver gate, connect-time trust, banner.
 
diff --git a/examples/hub-onboard-vite/README.md b/examples/hub-onboard-vite/README.md
new file mode 100644
index 00000000..334b122a
--- /dev/null
+++ b/examples/hub-onboard-vite/README.md
@@ -0,0 +1,26 @@
+# hub-onboard-vite
+
+A Vite host that ships only `@devframes/hub-ui-onboard` (about 20 kB in the browser) and installs the hub when the user asks for it.
+
+```sh
+pnpm --filter hub-onboard-vite dev
+```
+
+Open the printed URL. The button at the bottom left opens a panel with two actions:
+
+- Install runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
+- Hide for now hides the button for this browser tab.
+- Disable entirely writes `node_modules/.devframe/hub-ui-onboard.json`. The host reads `onboarding.disabled` on the next start and injects no script.
+
+When the three packages are already installed, the button never shows: the host's `onInstalled` runs on the first request and the real dock appears directly.
+
+Install changes this example's `package.json` and the lockfile. Run `git checkout -- examples/hub-onboard-vite pnpm-lock.yaml` and delete the state file to reset the demo.
+
+## How it works
+
+[`vite.config.ts`](./vite.config.ts) holds the whole integration:
+
+- `createOnboarding({ packages, branding, onInstalled })` returns `nodeMiddleware`, `scriptSrc`, `disabled` and `installed`.
+- `server.middlewares.use(onboarding.nodeMiddleware)` serves `/__devframes/embedded.js` and the `/__devframes/__onboard/*` routes.
+- `transformIndexHtml` injects `<script type="module" src="/__devframes/embedded.js">` unless the user disabled it earlier.
+- `onInstalled` resolves the new packages from the project root, calls `initHub` with Vite's HTTP server, and returns `hub.handler`. From then on every request under the base goes to the hub.
diff --git a/examples/hub-onboard-vite/index.html b/examples/hub-onboard-vite/index.html
new file mode 100644
index 00000000..244e9dc5
--- /dev/null
+++ b/examples/hub-onboard-vite/index.html
@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Hub onboarding (Vite)</title>
+  </head>
+  <body style="font-family: system-ui; padding: 2rem">
+    <h1>Hub onboarding (Vite)</h1>
+    <p>This host ships only <code>@devframes/hub-ui-onboard</code>. The button at the bottom left:</p>
+    <ul>
+      <li>is <code>/__devframes/embedded.js</code>, a 20 kB stand-in for the hub UI</li>
+      <li>installs <code>@devframes/hub</code>, <code>@devframes/hub-ui</code> and <code>@devframes/plugin-git</code> when you click Install</li>
+      <li>then hands <code>/__devframes/</code> to the real hub in this same process, no restart</li>
+      <li>hides for this tab when you click Hide for now</li>
+      <li>writes <code>node_modules/.devframe/hub-ui-onboard.json</code> when you click Disable entirely</li>
+    </ul>
+  </body>
+</html>
diff --git a/examples/hub-onboard-vite/package.json b/examples/hub-onboard-vite/package.json
new file mode 100644
index 00000000..8eb86419
--- /dev/null
+++ b/examples/hub-onboard-vite/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "hub-onboard-vite",
+  "type": "module",
+  "version": "1.2.1",
+  "private": true,
+  "description": "Vite host that ships only the hub UI onboarding button and installs the hub on demand.",
+  "homepage": "https://github.com/devframes/devframe/tree/main/examples/hub-onboard-vite",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@devframes/hub-ui-onboard": "workspace:*",
+    "@types/node": "catalog:types",
+    "vite": "catalog:build"
+  }
+}
diff --git a/examples/hub-onboard-vite/tsconfig.json b/examples/hub-onboard-vite/tsconfig.json
new file mode 100644
index 00000000..906a7ddc
--- /dev/null
+++ b/examples/hub-onboard-vite/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["esnext", "dom"],
+    "types": ["node"]
+  },
+  "include": ["vite.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}
diff --git a/examples/hub-onboard-vite/vite.config.ts b/examples/hub-onboard-vite/vite.config.ts
new file mode 100644
index 00000000..b1415684
--- /dev/null
+++ b/examples/hub-onboard-vite/vite.config.ts
@@ -0,0 +1,69 @@
+import type { Server } from 'node:http'
+import type { Plugin, ViteDevServer } from 'vite'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { createOnboarding } from '@devframes/hub-ui-onboard'
+import { defineConfig } from 'vite'
+
+const cwd = fileURLToPath(new URL('.', import.meta.url))
+const branding = { productName: 'Devframes on Vite', primaryColor: '#646cff' }
+
+/**
+ * Resolve from the project's own `package.json`, not from this file: the
+ * packages were installed into the project a moment ago, and under pnpm
+ * they are only reachable from there.
+ */
+const require = createRequire(join(cwd, 'package.json'))
+function load<T>(specifier: string): Promise<T> {
+  return import(pathToFileURL(require.resolve(specifier)).href)
+}
+
+/**
+ * The whole integration: serve the onboarding routes, inject its button, and
+ * once the hub is installed start it on the same base and HTTP server so the
+ * button can swap itself for the real dock.
+ */
+function hubOnboarding(): Plugin {
+  let server: ViteDevServer
+  const onboarding = createOnboarding({
+    cwd,
+    packages: ['@devframes/hub', '@devframes/hub-ui', '@devframes/plugin-git'],
+    branding,
+    async onInstalled() {
+      const [{ initHub }, { createUi }, { createGitDevframe }] = await Promise.all([
+        load<typeof import('@devframes/hub/initiate')>('@devframes/hub/initiate'),
+        load<typeof import('@devframes/hub-ui')>('@devframes/hub-ui'),
+        load<typeof import('@devframes/plugin-git')>('@devframes/plugin-git'),
+      ])
+      const hub = initHub({
+        base: '/__devframes/',
+        cwd,
+        // Vite's dev server is a plain `node:http` server unless `server.https` is set.
+        server: server.httpServer as Server,
+        ui: createUi({ branding }),
+        devframes: [createGitDevframe()],
+      })
+      return hub.handler
+    },
+  })
+
+  return {
+    name: 'hub-onboarding',
+    apply: 'serve',
+    configureServer(instance) {
+      server = instance
+      instance.middlewares.use(onboarding.nodeMiddleware)
+    },
+    transformIndexHtml() {
+      if (onboarding.disabled)
+        return []
+      return [{ tag: 'script', attrs: { type: 'module', src: onboarding.scriptSrc }, injectTo: 'body' }]
+    },
+  }
+}
+
+export default defineConfig({
+  server: { allowedHosts: true, strictPort: false },
+  plugins: [hubOnboarding()],
+})
diff --git a/packages/hub-ui-onboard/package.json b/packages/hub-ui-onboard/package.json
new file mode 100644
index 00000000..b6997333
--- /dev/null
+++ b/packages/hub-ui-onboard/package.json
@@ -0,0 +1,50 @@
+{
+  "name": "@devframes/hub-ui-onboard",
+  "type": "module",
+  "version": "1.2.1",
+  "description": "A tiny stand-in for the devframe hub UI: a floating button that installs it on demand.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "packages/hub-ui-onboard",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devtools",
+    "devframe",
+    "hub",
+    "onboard"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pnpm run build:css && tsdown && vite build --config vite.client.config.ts",
+    "build:css": "tsx scripts/build-css.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "turbo run build --filter=@devframes/hub-ui-onboard"
+  },
+  "dependencies": {
+    "nostics": "catalog:deps",
+    "package-manager-detector": "catalog:deps",
+    "tinyexec": "catalog:deps"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:types",
+    "tsdown": "catalog:build",
+    "tsx": "catalog:build",
+    "unocss": "catalog:frontend",
+    "vite": "catalog:build",
+    "vitest": "catalog:testing"
+  }
+}
diff --git a/packages/hub-ui-onboard/scripts/build-css.ts b/packages/hub-ui-onboard/scripts/build-css.ts
new file mode 100644
index 00000000..660bad8a
--- /dev/null
+++ b/packages/hub-ui-onboard/scripts/build-css.ts
@@ -0,0 +1,18 @@
+import { fileURLToPath } from 'node:url'
+import { buildShadowCss } from '../../../design/build-shadow-css'
+import config from '../uno.config'
+
+// Compiles the UnoCSS output into `src/client/.generated/css.ts`, adopted
+// into the floating button's shadow root.
+const SRC_DIR = fileURLToPath(new URL('../src/client', import.meta.url))
+
+const { sourceCount, css } = await buildShadowCss({
+  srcDir: SRC_DIR,
+  globs: ['**/*.ts'],
+  config,
+  primaryRampPath: fileURLToPath(new URL('../../../design/primary-ramp.css', import.meta.url)),
+  userStylePath: fileURLToPath(new URL('../src/client/style.css', import.meta.url)),
+  varPrefix: '--un-onboard-',
+  scanDesignComponents: false,
+})
+console.log(`CSS built (${sourceCount} sources, ${(css.length / 1024).toFixed(1)} kB)`)
diff --git a/packages/hub-ui-onboard/src/client/index.ts b/packages/hub-ui-onboard/src/client/index.ts
new file mode 100644
index 00000000..8087e52c
--- /dev/null
+++ b/packages/hub-ui-onboard/src/client/index.ts
@@ -0,0 +1,218 @@
+import type { OnboardingBranding, OnboardingStatus } from '../types'
+import css from './.generated/css'
+import { DEVFRAME_LOGO } from './logo'
+
+// @unocss-include
+
+/**
+ * The stand-in floating button, served at `<base>embedded.js`. It asks
+ * `__onboard/status` what to show, offers Install / Disable, and once the
+ * real hub answers at the same base it loads that `embedded.js` and removes
+ * itself.
+ */
+
+// Read through a variable so Vite's lib build keeps the runtime URL.
+const moduleUrl = import.meta.url
+const base = new URL('./', moduleUrl)
+const POLL_MS = 1000
+const HIDDEN_KEY = 'devframes-onboard-hidden'
+
+const api = (path: string, init?: RequestInit) => fetch(new URL(`__onboard/${path}`, base), init)
+
+async function fetchStatus(): Promise<OnboardingStatus> {
+  const response = await api('status')
+  return response.json()
+}
+
+async function handOff(): Promise<void> {
+  // A new query string so the browser does not return this module from its cache.
+  await import(/* @vite-ignore */ new URL(`embedded.js?onboard=${Date.now()}`, base).href)
+}
+
+function isDark(): boolean {
+  const stored = localStorage.getItem('devframes-color-scheme')
+  if (stored === 'dark' || stored === 'light')
+    return stored === 'dark'
+  return matchMedia('(prefers-color-scheme: dark)').matches
+}
+
+function logoFor(branding: OnboardingBranding): string | undefined {
+  const logo = branding.logo
+  if (!logo || typeof logo === 'string')
+    return logo
+  return isDark() ? (logo.dark ?? logo.light) : logo.light
+}
+
+function mark(branding: OnboardingBranding, className: string): HTMLElement {
+  const el = document.createElement('span')
+  el.className = `${className} flex items-center justify-center`
+  const src = logoFor(branding)
+  if (src) {
+    const img = document.createElement('img')
+    img.src = src
+    img.alt = ''
+    img.draggable = false
+    img.className = 'w-full h-full object-contain'
+    el.append(img)
+  }
+  else {
+    el.innerHTML = DEVFRAME_LOGO
+  }
+  return el
+}
+
+function button(className: string, label: string, onClick: () => void): HTMLButtonElement {
+  const el = document.createElement('button')
+  el.type = 'button'
+  el.className = className
+  el.textContent = label
+  el.addEventListener('click', onClick)
+  return el
+}
+
+function mount(initial: OnboardingStatus): void {
+  const host = document.createElement('devframes-onboard')
+  const root = host.attachShadow({ mode: 'open' })
+  const style = document.createElement('style')
+  style.textContent = css
+  const scheme = document.createElement('div')
+  scheme.className = [
+    isDark() ? 'dark' : 'light',
+    'devframes-onboard-root',
+  ].join(' ')
+  scheme.style.display = 'contents'
+  root.append(style, scheme)
+  if (initial.branding.primaryColor)
+    host.style.setProperty('--devframe-primary', initial.branding.primaryColor)
+
+  const { messages, branding } = initial
+
+  const pill = document.createElement('button')
+  pill.type = 'button'
+  pill.className = 'devframes-onboard-pill'
+  pill.title = messages.title
+  pill.setAttribute('aria-haspopup', 'dialog')
+  pill.setAttribute('aria-expanded', 'false')
+  const glow = document.createElement('span')
+  glow.className = 'devframes-onboard-glow'
+  pill.append(mark(branding, 'w-3 h-3'))
+
+  const panel = document.createElement('div')
+  panel.className = 'devframes-onboard-panel'
+  panel.setAttribute('role', 'dialog')
+  panel.hidden = true
+
+  const heading = document.createElement('div')
+  heading.className = 'flex items-center gap-2 font-medium'
+  const title = document.createElement('span')
+  title.textContent = messages.title
+  heading.append(mark(branding, 'w-5 h-5'), title)
+
+  const description = document.createElement('p')
+  description.className = 'color-muted m-0'
+  description.textContent = messages.description
+
+  const command = document.createElement('code')
+  command.className = 'devframes-onboard-command'
+  command.textContent = initial.command
+
+  const note = document.createElement('p')
+  note.className = 'm-0 text-xs'
+  note.hidden = true
+
+  const install = button('btn-primary text-sm justify-center', messages.install, () => void startInstall())
+  const hide = button('btn-action justify-center text-sm color-muted', messages.hide, () => {
+    sessionStorage.setItem(HIDDEN_KEY, '1')
+    host.remove()
+  })
+  const disable = button('btn-action justify-center text-sm color-muted', messages.disable, () => void disableDevtools())
+  const secondary = document.createElement('div')
+  secondary.className = 'grid grid-cols-2 gap-1'
+  secondary.append(hide, disable)
+  const actions = document.createElement('div')
+  actions.className = 'flex flex-col gap-2'
+  actions.append(secondary, install)
+
+  panel.append(heading, description, command, note, actions)
+  scheme.append(glow, pill, panel)
+
+  let open = false
+  const setOpen = (value: boolean) => {
+    open = value
+    panel.hidden = !open
+    pill.setAttribute('aria-expanded', String(open))
+  }
+  pill.addEventListener('click', () => setOpen(!open))
+  document.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape' && open)
+      setOpen(false)
+  })
+  document.addEventListener('pointerdown', (event) => {
+    if (open && !event.composedPath().includes(host))
+      setOpen(false)
+  })
+
+  function render(status: OnboardingStatus): void {
+    const { state } = status
+    install.disabled = state === 'installing'
+    install.textContent = state === 'error' ? messages.retry : messages.install
+    install.hidden = state === 'installed'
+    note.hidden = !(state === 'installing' || state === 'installed' || state === 'error')
+    note.className = `m-0 text-xs ${state === 'error' ? 'text-red-600 dark:text-red-400' : 'color-muted'}`
+    note.textContent = state === 'installing'
+      ? messages.installing
+      : state === 'installed'
+        ? messages.restart
+        : state === 'error'
+          ? `${status.error?.code}: ${status.error?.message}`
+          : ''
+  }
+
+  async function poll(): Promise<void> {
+    const status = await fetchStatus()
+    if (status.state === 'ready') {
+      host.remove()
+      await handOff()
+      return
+    }
+    render(status)
+    if (status.state === 'installing')
+      setTimeout(() => void poll(), POLL_MS)
+  }
+
+  async function startInstall(): Promise<void> {
+    render({ ...initial, state: 'installing' })
+    await api('install', { method: 'POST' })
+    await poll()
+  }
+
+  async function disableDevtools(): Promise<void> {
+    const response = await api('disable', { method: 'POST' })
+    if (response.ok)
+      host.remove()
+  }
+
+  render(initial)
+  if (initial.state === 'installing')
+    void poll()
+  document.body.append(host)
+}
+
+async function main(): Promise<void> {
+  // Never stack a second button inside an iframe of the same origin.
+  if (window.parent !== window)
+    return
+  if (sessionStorage.getItem(HIDDEN_KEY))
+    return
+  const status = await fetchStatus()
+  // Nothing to offer: disabled by the user, or already installed with no hub to hand off to.
+  if (status.state === 'disabled' || status.state === 'installed')
+    return
+  if (status.state === 'ready') {
+    await handOff()
+    return
+  }
+  mount(status)
+}
+
+void main()
diff --git a/packages/hub-ui-onboard/src/client/logo.ts b/packages/hub-ui-onboard/src/client/logo.ts
new file mode 100644
index 00000000..d362ccb0
--- /dev/null
+++ b/packages/hub-ui-onboard/src/client/logo.ts
@@ -0,0 +1,2 @@
+/** The devframe mark (`docs/public/logo.svg`), inlined so the pill paints with no network fetch. */
+export const DEVFRAME_LOGO = `<svg viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Devframe logo"><path d="M238.464 40H66V236.007H104.577C220.688 236.007 232.79 158.437 232.79 121.733C232.79 108.867 243.38 108.867 243.38 121.733C251.318 236.701 356.35 245.457 365.527 246.223L365.542 246.224C374.619 246.981 382.561 251.521 365.542 254.548C253.592 264.765 243.758 364.282 243.38 375.634C243.002 386.986 235.438 399.851 232.79 375.634C222.957 274.603 144.289 257.954 104.577 257.954H66V460.772H238.464C358.356 460.772 452.152 371.472 452.152 251.521C452.152 131.571 356.465 40 238.464 40Z" fill="url(#devframes-onboard-logo-gradient)" stroke="#86997F" stroke-opacity="0.5" stroke-width="1.33156"/><defs><radialGradient id="devframes-onboard-logo-gradient" cx="0" cy="0" r="1" gradientTransform="matrix(399.011 555.102 -568.423 408.982 -11.6221 -34.9218)" gradientUnits="userSpaceOnUse"><stop stop-color="#ADC77F"/><stop offset="0.71903" stop-color="#517158"/><stop offset="1" stop-color="#486954"/></radialGradient></defs></svg>`
diff --git a/packages/hub-ui-onboard/src/client/style.css b/packages/hub-ui-onboard/src/client/style.css
new file mode 100644
index 00000000..93e2d009
--- /dev/null
+++ b/packages/hub-ui-onboard/src/client/style.css
@@ -0,0 +1,63 @@
+/*
+ * Adopted into the button's shadow root, so nothing here reaches the host
+ * page. Class names are prefixed anyway so the generated stylesheet reads
+ * clearly next to the utilities.
+ */
+.devframes-onboard-root:hover .devframes-onboard-glow {
+  --uno: opacity-60;
+}
+
+.devframes-onboard-pill {
+  --uno: fixed bottom-4 left-4 z-floating-anchor w-6 h-6 rounded-full border border-base bg-dock-glass shadow;
+  --uno: flex items-center justify-center cursor-pointer select-none p-0 outline-none;
+  --uno: op25 hover:op100 focus-visible:op100 focus-visible:ring-2 ring-primary-400;
+  --uno: transition-all duration-200 hover:scale-105;
+}
+
+/* Full opacity while the panel is open, so the pill reads as its anchor. */
+.devframes-onboard-pill[aria-expanded='true'] {
+  --uno: op100;
+}
+
+.devframes-onboard-glow {
+  --uno: absolute left--4 bottom--26 w-40 h-40 rounded-full opacity-0 pointer-events-none -z-1;
+  --uno: transition-opacity duration-1000 ease-out;
+  transform: translate(-50%, -50%);
+  filter: blur(60px);
+  /* Same brand-derived gradient as the hub-ui dock glow. */
+  background-image: linear-gradient(
+    45deg,
+    var(--colors-primary-300, #adc77f),
+    var(--colors-primary-500, #517158),
+    var(--colors-primary-DEFAULT, #486954)
+  );
+}
+
+.devframes-onboard-panel {
+  --uno: fixed bottom-12 left-4 z-floating-anchor w-80 max-w-[calc(100vw-2rem)] rounded-lg border border-base bg-base color-base shadow-lg;
+  --uno: p-4 flex flex-col gap-3 font-sans text-sm leading-normal;
+  --uno: transition-all duration-200 origin-bottom-left;
+}
+
+.devframes-onboard-panel[hidden] {
+  --uno: block op0 scale-95 pointer-events-none;
+}
+
+.devframes-onboard-command {
+  --uno: block font-mono text-xs px-2 py-1.5 rounded bg-secondary color-muted break-all select-all;
+}
+
+@media print {
+  .devframes-onboard-pill,
+  .devframes-onboard-panel {
+    --uno: hidden;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .devframes-onboard-pill,
+  .devframes-onboard-panel,
+  .devframes-onboard-glow {
+    transition: none;
+  }
+}
diff --git a/packages/hub-ui-onboard/src/diagnostics.ts b/packages/hub-ui-onboard/src/diagnostics.ts
new file mode 100644
index 00000000..c2151d49
--- /dev/null
+++ b/packages/hub-ui-onboard/src/diagnostics.ts
@@ -0,0 +1,33 @@
+import { createConsoleReporter, defineDiagnostics } from 'nostics'
+
+/**
+ * `DF90xx` is this package's range (see `.agents/08-diagnostics.md`). It
+ * uses `nostics` directly: the package must stay free of `devframe` so a
+ * host can ship it while devframe itself is not installed.
+ */
+export const diagnostics = defineDiagnostics({
+  docsBase: 'https://devfra.me/errors',
+  reporters: [createConsoleReporter()],
+  codes: {
+    DF9000: {
+      why: '`createOnboarding()` received no packages to install.',
+      fix: 'Pass at least one package spec in `packages`, for example `packages: [\'@nuxt/devtools\']`.',
+    },
+    DF9001: {
+      why: (p: { command: string, exitCode: number | undefined, stderr: string }) => `\`${p.command}\` exited with code ${p.exitCode ?? 'unknown'}.${p.stderr ? `\n${p.stderr}` : ''}`,
+      fix: 'Run the command in a terminal to see the package manager\'s full output, then click Install again.',
+    },
+    DF9002: {
+      why: (p: { name: string, cwd: string }) => `The install finished, but "${p.name}" is not in ${p.cwd}/node_modules.`,
+      fix: 'Make sure that `cwd` points at the project that should receive the dependency (in a workspace, the package that runs the dev server).',
+    },
+    DF9003: {
+      why: (p: { reason: string }) => `\`onInstalled\` threw after the packages were installed: ${p.reason}`,
+      fix: 'The packages are installed. Fix the error in your `onInstalled` callback, or restart the dev server to load them.',
+    },
+    DF9004: {
+      why: (p: { file: string }) => `The onboarding state file ${p.file} could not be read or written.`,
+      fix: 'Make sure that `stateDir` is writable, or point it at another directory.',
+    },
+  },
+})
diff --git a/packages/hub-ui-onboard/src/index.ts b/packages/hub-ui-onboard/src/index.ts
new file mode 100644
index 00000000..98285a26
--- /dev/null
+++ b/packages/hub-ui-onboard/src/index.ts
@@ -0,0 +1,231 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { ResolvedCommand } from 'package-manager-detector'
+import type { CreateOnboardingOptions, Onboarding, OnboardingHandler, OnboardingMessages, OnboardingState, OnboardingStatus } from './types'
+import { Buffer } from 'node:buffer'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import process from 'node:process'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { fileURLToPath } from 'node:url'
+import { Diagnostic } from 'nostics'
+import { diagnostics } from './diagnostics'
+import { formatCommand, packagesInstalled, resolveInstallCommand, runInstall } from './install'
+
+export type * from './types'
+
+const STATE_FILE = 'hub-ui-onboard.json'
+
+/** `devframes` → `/devframes/`, same rule as `normalizeHubBase` in `@devframes/hub`. */
+function normalizeBase(base: string): string {
+  return `/${base}/`.replace(/\/{2,}/g, '/')
+}
+
+/**
+ * The built button lives next to the built entry (`dist/index.mjs` →
+ * `dist/client/embedded.js`). Running from source (tests), fall back to
+ * the package's `dist/`.
+ */
+function clientFile(): string {
+  const here = fileURLToPath(new URL('.', import.meta.url))
+  const sibling = join(here, 'client/embedded.js')
+  return existsSync(sibling) ? sibling : join(here, '../dist/client/embedded.js')
+}
+
+function defaultMessages(productName: string): OnboardingMessages {
+  return {
+    title: productName,
+    description: `${productName} enables development features in your project. Install it with:`,
+    install: `Install ${productName}`,
+    hide: 'Hide for now',
+    disable: 'Disable entirely',
+    installing: 'Installing...',
+    restart: `Installed. Restart your dev server to open ${productName}.`,
+    retry: 'Retry',
+  }
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, { status, headers: { 'Cache-Control': 'no-store' } })
+}
+
+/**
+ * A browser sends `Origin` on every POST. Any other page on the same machine
+ * must not be able to start an install, so the origin has to match the
+ * request's own host (port included, which `Sec-Fetch-Site: same-site` ignores).
+ */
+function isSameOrigin(request: Request): boolean {
+  const origin = request.headers.get('origin')
+  if (origin)
+    return new URL(origin).host === new URL(request.url).host
+  const site = request.headers.get('sec-fetch-site')
+  return !site || site === 'same-origin' || site === 'none'
+}
+
+function readDisabled(file: string): boolean {
+  if (!existsSync(file))
+    return false
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')).disabled === true
+  }
+  catch (cause) {
+    diagnostics.DF9004({ file, cause })
+    return false
+  }
+}
+
+async function toRequest(req: IncomingMessage): Promise<Request> {
+  const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`)
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(req.headers)) {
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item !== undefined)
+        headers.append(name, item)
+    }
+  }
+  const method = req.method ?? 'GET'
+  const body = method === 'GET' || method === 'HEAD' ? undefined : Buffer.concat(await req.toArray())
+  return new Request(url, { method, headers, body })
+}
+
+async function sendResponse(res: ServerResponse, response: Response): Promise<void> {
+  res.statusCode = response.status
+  response.headers.forEach((value, name) => res.setHeader(name, value))
+  if (!response.body) {
+    res.end()
+    return
+  }
+  // `fromWeb` wants Node's own ReadableStream type; the runtime object is the same.
+  await pipeline(Readable.fromWeb(response.body as import('node:stream/web').ReadableStream), res).catch((cause: unknown) => {
+    // The browser closed the connection (navigation, aborted poll); nothing is left to send.
+    if (!(cause instanceof Error && 'code' in cause && cause.code === 'ERR_STREAM_PREMATURE_CLOSE'))
+      throw cause
+  })
+}
+
+/**
+ * Create the stand-in for a hub UI that is not installed yet: a request
+ * handler that serves the floating button at `<base>embedded.js` and the
+ * `__onboard/*` routes it talks to.
+ */
+export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
+  if (options.packages.length === 0)
+    throw diagnostics.DF9000()
+
+  const base = normalizeBase(options.base ?? '/__devframes/')
+  const cwd = options.cwd ?? process.cwd()
+  const stateFile = join(options.stateDir ?? join(cwd, 'node_modules/.devframe'), STATE_FILE)
+  const plan = { cwd, packages: options.packages, dev: options.dev ?? true }
+  const branding = options.branding ?? {}
+  const messages = { ...defaultMessages(branding.productName?.trim() || 'Devframes'), ...options.messages }
+
+  const disabled = readDisabled(stateFile)
+  const installed = !disabled && packagesInstalled(plan)
+  let state: OnboardingState = disabled ? 'disabled' : installed ? 'installed' : 'idle'
+  let error: OnboardingStatus['error']
+  let delegate: OnboardingHandler | undefined
+  let command: Promise<ResolvedCommand> | undefined
+  const getCommand = () => command ??= resolveInstallCommand(plan)
+
+  function fail(cause: unknown, fallback: () => Diagnostic): void {
+    const diagnostic = cause instanceof Diagnostic ? cause : fallback()
+    error = { code: diagnostic.code, message: diagnostic.message }
+    state = 'error'
+  }
+
+  /** Hand the base to the host's hub, if it offers one. */
+  async function activate(): Promise<void> {
+    try {
+      const next = await options.onInstalled?.()
+      delegate = typeof next === 'function' ? next : undefined
+      state = delegate ? 'ready' : 'installed'
+    }
+    catch (cause) {
+      fail(cause, () => diagnostics.DF9003({ reason: cause instanceof Error ? cause.message : String(cause), cause }))
+    }
+  }
+
+  async function install(): Promise<void> {
+    state = 'installing'
+    error = undefined
+    let resolved: ResolvedCommand | undefined
+    try {
+      resolved = await getCommand()
+      await runInstall(plan, resolved)
+    }
+    catch (cause) {
+      const command = resolved ? formatCommand(resolved) : plan.packages.join(' ')
+      fail(cause, () => diagnostics.DF9001({ command, exitCode: undefined, stderr: String(cause) }))
+      return
+    }
+    await activate()
+  }
+
+  // Already installed: the hub takes over on the first request. Not earlier,
+  // because the host's `onInstalled` may need a server that exists only later.
+  let activated: Promise<void> | undefined
+
+  function disable(): Response {
+    try {
+      mkdirSync(join(stateFile, '..'), { recursive: true })
+      writeFileSync(stateFile, JSON.stringify({ disabled: true }))
+    }
+    catch (cause) {
+      const diagnostic = diagnostics.DF9004({ file: stateFile, cause })
+      return json({ code: diagnostic.code, message: diagnostic.message }, 500)
+    }
+    state = 'disabled'
+    return new Response(null, { status: 204 })
+  }
+
+  async function status(): Promise<OnboardingStatus> {
+    return { state, command: formatCommand(await getCommand()), branding, messages, error }
+  }
+
+  const handler: OnboardingHandler = async (request) => {
+    if (installed)
+      await (activated ??= activate())
+    if (delegate)
+      return delegate(request)
+    const { pathname } = new URL(request.url)
+    if (!pathname.startsWith(base))
+      return new Response(null, { status: 404 })
+    const route = `${request.method} ${pathname.slice(base.length)}`
+
+    if (route === 'GET embedded.js') {
+      return new Response(await readFile(clientFile()), {
+        headers: { 'Content-Type': 'text/javascript; charset=utf-8', 'Cache-Control': 'no-store' },
+      })
+    }
+    if (route === 'GET __onboard/status')
+      return json(await status())
+    if (route === 'POST __onboard/install' || route === 'POST __onboard/disable') {
+      if (!isSameOrigin(request))
+        return new Response(null, { status: 403 })
+      if (route.endsWith('disable'))
+        return disable()
+      if (state === 'idle' || state === 'error')
+        void install()
+      return new Response(null, { status: 202 })
+    }
+    return new Response(null, { status: 404 })
+  }
+
+  return {
+    handler,
+    nodeMiddleware(req, res, next) {
+      if (!(req.url ?? '/').startsWith(base)) {
+        next?.()
+        return
+      }
+      toRequest(req)
+        .then(request => handler(request))
+        .then(response => sendResponse(res, response))
+        .catch(cause => next ? next(cause) : res.destroy(cause))
+    },
+    disabled,
+    installed,
+    scriptSrc: `${base}embedded.js`,
+  }
+}
diff --git a/packages/hub-ui-onboard/src/install.ts b/packages/hub-ui-onboard/src/install.ts
new file mode 100644
index 00000000..9b5515ae
--- /dev/null
+++ b/packages/hub-ui-onboard/src/install.ts
@@ -0,0 +1,77 @@
+import type { ResolvedCommand } from 'package-manager-detector'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import process from 'node:process'
+import { detect, resolveCommand } from 'package-manager-detector'
+import { exec } from 'tinyexec'
+import { diagnostics } from './diagnostics'
+
+export interface InstallPlan {
+  cwd: string
+  packages: string[]
+  dev: boolean
+}
+
+/** The `add` command for the project's package manager, `npm` when none is detected. */
+export async function resolveInstallCommand(plan: InstallPlan): Promise<ResolvedCommand> {
+  const detected = await detect({ cwd: plan.cwd })
+  const agent = detected?.agent ?? 'npm'
+  const args = [...(plan.dev ? ['-D'] : []), ...plan.packages]
+  // `add` exists for every agent the detector knows, so the null branch is unreachable.
+  return resolveCommand(agent, 'add', args)!
+}
+
+export function formatCommand(command: ResolvedCommand): string {
+  return [command.command, ...command.args].join(' ')
+}
+
+/**
+ * Run the install and make sure that each named package landed in
+ * `<cwd>/node_modules`. Throws a `DF9001` / `DF9002` diagnostic on failure.
+ */
+export async function runInstall(plan: InstallPlan, command: ResolvedCommand): Promise<void> {
+  const result = await exec(command.command, command.args, {
+    // `CI` keeps every package manager non-interactive: nobody can answer a prompt here.
+    nodeOptions: { cwd: plan.cwd, env: { ...process.env, CI: '1' } },
+  })
+  if (result.exitCode !== 0) {
+    throw diagnostics.DF9001({
+      command: formatCommand(command),
+      exitCode: result.exitCode,
+      stderr: result.stderr.trim().slice(-2048),
+    })
+  }
+  for (const name of namedPackages(plan)) {
+    if (!isInstalled(plan.cwd, name))
+      throw diagnostics.DF9002({ name, cwd: plan.cwd })
+  }
+}
+
+/**
+ * `true` when every named package is already in `<cwd>/node_modules`, so the
+ * onboarding has nothing to install. Path, URL and alias specs cannot be
+ * checked by name, so a plan made only of those is never "already installed".
+ */
+export function packagesInstalled(plan: InstallPlan): boolean {
+  const names = namedPackages(plan)
+  return names.length > 0 && names.every(name => isInstalled(plan.cwd, name))
+}
+
+function isInstalled(cwd: string, name: string): boolean {
+  return existsSync(join(cwd, 'node_modules', name))
+}
+
+function namedPackages(plan: InstallPlan): string[] {
+  return plan.packages.map(packageName).filter((name): name is string => name !== undefined)
+}
+
+/**
+ * The package name of a bare spec (`foo`, `@scope/foo@^1`), or `undefined`
+ * for a path, URL or alias spec whose installed name is not in the spec.
+ */
+function packageName(spec: string): string | undefined {
+  // npm name characters only, so `file:`, `link:`, `npm:` aliases, URLs and
+  // Windows paths (`file:D:\pkg`) never pass as a name.
+  const match = /^((?:@[\w.~-]+\/)?[\w.~-]+)(?:@[^/]*)?$/.exec(spec)
+  return match?.[1]
+}
diff --git a/packages/hub-ui-onboard/src/types.ts b/packages/hub-ui-onboard/src/types.ts
new file mode 100644
index 00000000..b629270a
--- /dev/null
+++ b/packages/hub-ui-onboard/src/types.ts
@@ -0,0 +1,82 @@
+/** A logo URL, or one per color scheme. Same shape as hub-ui's `BrandingLogo`. */
+export type OnboardingLogo = string | { light: string, dark?: string }
+
+/** The subset of hub-ui's `DevframeBranding` the two-button panel renders. */
+export interface OnboardingBranding {
+  /** Product name shown in the panel and used in the default strings. Default: `Devframes`. */
+  productName?: string
+  logo?: OnboardingLogo
+  /** Primary accent as a CSS color; retints the pill glow and the primary button. */
+  primaryColor?: string
+}
+
+/** Every string the panel renders. Defaults derive from `branding.productName`. */
+export interface OnboardingMessages {
+  /** Pill tooltip and panel heading. */
+  title: string
+  /** Short sentence under the heading. */
+  description: string
+  install: string
+  /** Hides the button for this browser tab (`sessionStorage`). */
+  hide: string
+  /** Writes the state file; the host stops injecting the button. */
+  disable: string
+  installing: string
+  /** Shown when the install finished and no hot swap happened. */
+  restart: string
+  retry: string
+}
+
+/** A web-standard request handler the hub exposes once installed. */
+export type OnboardingHandler = (request: Request) => Response | Promise<Response>
+
+export interface CreateOnboardingOptions {
+  /** Packages to install when the user clicks Install. Package specs as the package manager accepts them. */
+  packages: string[]
+  /** Mount base. Default: the hub default `/__devframes/`. */
+  base?: string
+  /** Project directory the install runs in. Default: `process.cwd()`. */
+  cwd?: string
+  /** Directory of the `hub-ui-onboard.json` state file. Default: `<cwd>/node_modules/.devframe`. */
+  stateDir?: string
+  /** Install as a devDependency. Default: `true`. */
+  dev?: boolean
+  branding?: OnboardingBranding
+  messages?: Partial<OnboardingMessages>
+  /**
+   * Called once the packages are installed and verified. Return a handler
+   * to take over every request at `base` in this process; the floating
+   * button then loads `<base>embedded.js` from it. Return nothing to ask the
+   * user to restart the dev server.
+   */
+  onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>
+}
+
+export type OnboardingState = 'idle' | 'installing' | 'installed' | 'ready' | 'error' | 'disabled'
+
+/** The `GET <base>__onboard/status` body. */
+export interface OnboardingStatus {
+  state: OnboardingState
+  /** The exact command Install runs, for the panel's preview line. */
+  command: string
+  branding: OnboardingBranding
+  messages: OnboardingMessages
+  error?: { code: string, message: string }
+}
+
+export interface Onboarding {
+  /** Web-standard handler for every request under `base`. */
+  handler: OnboardingHandler
+  /** Connect-style bridge for Node servers (Vite, Express, Fastify with middie). */
+  nodeMiddleware: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, next?: (err?: unknown) => void) => void
+  /** `true` when the user disabled DevTools in an earlier session; skip injecting `scriptSrc`. */
+  disabled: boolean
+  /**
+   * `true` when every named package was already in `node_modules` at
+   * creation. `onInstalled` then runs on the first request, which already
+   * reaches its handler; the button never shows.
+   */
+  installed: boolean
+  /** `<base>embedded.js`: the `<script type="module">` URL to inject. */
+  scriptSrc: string
+}
diff --git a/packages/hub-ui-onboard/test/fixtures/pkg/package.json b/packages/hub-ui-onboard/test/fixtures/pkg/package.json
new file mode 100644
index 00000000..c66c0ae7
--- /dev/null
+++ b/packages/hub-ui-onboard/test/fixtures/pkg/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "onboard-fixture",
+  "version": "0.0.0",
+  "private": true
+}
diff --git a/packages/hub-ui-onboard/test/onboarding.test.ts b/packages/hub-ui-onboard/test/onboarding.test.ts
new file mode 100644
index 00000000..1dc8d906
--- /dev/null
+++ b/packages/hub-ui-onboard/test/onboarding.test.ts
@@ -0,0 +1,177 @@
+import type { AddressInfo } from 'node:net'
+import type { Onboarding, OnboardingStatus } from '../src/types'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createOnboarding } from '../src'
+
+const FIXTURE = fileURLToPath(new URL('./fixtures/pkg', import.meta.url))
+
+// The install test spawns a real npm; keep it offline and quiet.
+process.env.npm_config_audit = 'false'
+process.env.npm_config_fund = 'false'
+process.env.npm_config_update_notifier = 'false'
+
+const cleanups: (() => void)[] = []
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0))
+    cleanup()
+})
+
+function tempProject(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'onboard-'))
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'host', private: true }))
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function serve(onboarding: Onboarding): Promise<string> {
+  const server = createServer((req, res) => {
+    onboarding.nodeMiddleware(req, res, () => {
+      res.statusCode = 404
+      res.end('outside')
+    })
+  })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+  cleanups.push(() => server.close())
+  return `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+}
+
+async function status(origin: string): Promise<OnboardingStatus> {
+  const response = await fetch(`${origin}/__devframes/__onboard/status`)
+  return response.json()
+}
+
+async function waitFor<T>(read: () => Promise<T>, done: (value: T) => boolean): Promise<T> {
+  for (;;) {
+    const current = await read()
+    if (done(current))
+      return current
+    await new Promise(resolve => setTimeout(resolve, 200))
+  }
+}
+
+const settled = (s: OnboardingStatus) => s.state !== 'installing' && s.state !== 'idle'
+
+describe('createOnboarding', () => {
+  it('refuses an empty package list', () => {
+    expect(() => createOnboarding({ packages: [] })).toThrow(expect.objectContaining({ code: 'DF9000' }))
+  })
+
+  it('serves the button and reports an idle status with derived strings', async () => {
+    const cwd = tempProject()
+    const onboarding = createOnboarding({ cwd, packages: ['@nuxt/devtools'], branding: { productName: 'Nuxt DevTools' } })
+    const origin = await serve(onboarding)
+
+    expect(onboarding.scriptSrc).toBe('/__devframes/embedded.js')
+    expect(onboarding.disabled).toBe(false)
+
+    const script = await fetch(`${origin}/__devframes/embedded.js`)
+    expect(script.headers.get('content-type')).toContain('text/javascript')
+    expect(await script.text()).toContain('devframes-onboard')
+
+    const current = await status(origin)
+    expect(current.state).toBe('idle')
+    expect(current.command).toBe('npm i -D @nuxt/devtools')
+    expect(current.messages.install).toBe('Install Nuxt DevTools')
+    expect(current.messages.disable).toBe('Disable entirely')
+    expect(current.branding.productName).toBe('Nuxt DevTools')
+
+    expect((await fetch(`${origin}/__devframes/nope`)).status).toBe(404)
+    expect(await (await fetch(`${origin}/elsewhere`)).text()).toBe('outside')
+  })
+
+  it('honors a custom base and message overrides', async () => {
+    const onboarding = createOnboarding({ cwd: tempProject(), base: 'tools', packages: ['x'], messages: { install: 'Go' } })
+    const origin = await serve(onboarding)
+    expect(onboarding.scriptSrc).toBe('/tools/embedded.js')
+    const response = await fetch(`${origin}/tools/__onboard/status`)
+    expect(((await response.json()) as OnboardingStatus).messages.install).toBe('Go')
+  })
+
+  it('rejects a cross-origin install or disable', async () => {
+    const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
+    for (const action of ['install', 'disable']) {
+      const response = await fetch(`${origin}/__devframes/__onboard/${action}`, {
+        method: 'POST',
+        headers: { origin: 'http://evil.localhost:1' },
+      })
+      expect(response.status).toBe(403)
+    }
+    expect((await status(origin)).state).toBe('idle')
+  })
+
+  it('persists disable on disk for the next process', async () => {
+    const cwd = tempProject()
+    const origin = await serve(createOnboarding({ cwd, packages: ['x'] }))
+    const response = await fetch(`${origin}/__devframes/__onboard/disable`, { method: 'POST', headers: { origin } })
+    expect(response.status).toBe(204)
+    expect((await status(origin)).state).toBe('disabled')
+
+    const file = join(cwd, 'node_modules/.devframe/hub-ui-onboard.json')
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual({ disabled: true })
+    expect(createOnboarding({ cwd, packages: ['x'] }).disabled).toBe(true)
+  })
+
+  it('installs with the real package manager and hands the base to onInstalled', async () => {
+    const cwd = tempProject()
+    const onboarding = createOnboarding({
+      cwd,
+      packages: [`file:${FIXTURE}`],
+      onInstalled: () => () => new Response('hub here'),
+    })
+    const origin = await serve(onboarding)
+
+    const accepted = await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
+    expect(accepted.status).toBe(202)
+
+    const script = () => fetch(`${origin}/__devframes/embedded.js`).then(r => r.text())
+    expect(await waitFor(script, body => body === 'hub here')).toBe('hub here')
+    expect(existsSync(join(cwd, 'node_modules/onboard-fixture/package.json'))).toBe(true)
+    expect(await (await fetch(`${origin}/__devframes/__onboard/status`)).text()).toBe('hub here')
+  })
+
+  it('hands the base over at once when the packages are already installed', async () => {
+    const cwd = tempProject()
+    mkdirSync(join(cwd, 'node_modules/onboard-fixture'), { recursive: true })
+    const onboarding = createOnboarding({
+      cwd,
+      packages: ['onboard-fixture', 'file:/never/installed'],
+      onInstalled: () => () => new Response('hub here'),
+    })
+    expect(onboarding.installed).toBe(true)
+    const origin = await serve(onboarding)
+    expect(await (await fetch(`${origin}/__devframes/embedded.js`)).text()).toBe('hub here')
+  })
+
+  it('reports installed, and serves no button, when the packages exist but the host offers no hub', async () => {
+    const cwd = tempProject()
+    mkdirSync(join(cwd, 'node_modules/onboard-fixture'), { recursive: true })
+    const onboarding = createOnboarding({ cwd, packages: ['onboard-fixture'] })
+    const origin = await serve(onboarding)
+    expect(onboarding.installed).toBe(true)
+    expect((await status(origin)).state).toBe('installed')
+  })
+
+  it('reports a failed install as an error the client can retry', async () => {
+    const cwd = tempProject()
+    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'] }))
+    await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
+    const final = await waitFor(() => status(origin), s => s.state === 'error')
+    expect(final.error?.code).toBe('DF9001')
+    expect(final.error?.message).toContain('npm i -D file:/nonexistent/onboard-missing')
+  })
+
+  it('asks for a restart when onInstalled returns nothing', async () => {
+    const cwd = tempProject()
+    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false }))
+    await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
+    const final = await waitFor(() => status(origin), settled)
+    expect(final.state).toBe('installed')
+    expect(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).dependencies).toHaveProperty('onboard-fixture')
+  })
+})
diff --git a/packages/hub-ui-onboard/test/size.test.ts b/packages/hub-ui-onboard/test/size.test.ts
new file mode 100644
index 00000000..55b67bb9
--- /dev/null
+++ b/packages/hub-ui-onboard/test/size.test.ts
@@ -0,0 +1,25 @@
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { expect, it } from 'vitest'
+
+const DIST = fileURLToPath(new URL('../dist', import.meta.url))
+
+/** The whole point of this package is its install size; these budgets keep it honest. */
+const CLIENT_BUDGET = 40 * 1024
+const DIST_BUDGET = 150 * 1024
+
+function totalSize(dir: string): number {
+  return readdirSync(dir, { withFileTypes: true }).reduce((sum, entry) => {
+    const path = join(dir, entry.name)
+    return sum + (entry.isDirectory() ? totalSize(path) : statSync(path).size)
+  }, 0)
+}
+
+it('keeps the floating button under budget', () => {
+  expect(statSync(join(DIST, 'client/embedded.js')).size).toBeLessThan(CLIENT_BUDGET)
+})
+
+it('keeps the published files under budget', () => {
+  expect(totalSize(DIST)).toBeLessThan(DIST_BUDGET)
+})
diff --git a/packages/hub-ui-onboard/tsconfig.json b/packages/hub-ui-onboard/tsconfig.json
new file mode 100644
index 00000000..ae851e4d
--- /dev/null
+++ b/packages/hub-ui-onboard/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", "scripts", "test", "*.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/hub-ui-onboard/tsdown.config.ts b/packages/hub-ui-onboard/tsdown.config.ts
new file mode 100644
index 00000000..e9d89417
--- /dev/null
+++ b/packages/hub-ui-onboard/tsdown.config.ts
@@ -0,0 +1,16 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * Node-side entry only (`createOnboarding()`). The browser bundle is built
+ * by `vite.client.config.ts` into `dist/client/embedded.js`.
+ */
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+  },
+  outExtensions: () => ({ js: '.mjs', dts: '.d.mts' }),
+  clean: false,
+  tsconfig: '../../tsconfig.base.json',
+  dts: true,
+  platform: 'node',
+})
diff --git a/packages/hub-ui-onboard/uno.config.ts b/packages/hub-ui-onboard/uno.config.ts
new file mode 100644
index 00000000..c1845129
--- /dev/null
+++ b/packages/hub-ui-onboard/uno.config.ts
@@ -0,0 +1,23 @@
+import { mergeConfigs, presetWind3 } from 'unocss'
+import { createDesignConfig, shadowSurfaceSafelist } from '../../design/uno.config'
+
+/**
+ * Same shared design base as `@devframes/hub-ui`, on Wind3 because the
+ * stylesheet is adopted into a shadow root (see `design/uno.config.ts`).
+ * Compiled ahead of time by `scripts/build-css.ts`.
+ */
+export default mergeConfigs([
+  createDesignConfig({ base: presetWind3() }),
+  {
+    safelist: shadowSurfaceSafelist,
+    content: {
+      pipeline: {
+        include: [/\.ts$/],
+      },
+    },
+    shortcuts: {
+      'bg-dock-glass': 'bg-glass dark:bg-[#111]/80',
+      'z-floating-anchor': 'z-[2147483644]',
+    },
+  },
+])
diff --git a/packages/hub-ui-onboard/vite.client.config.ts b/packages/hub-ui-onboard/vite.client.config.ts
new file mode 100644
index 00000000..60e65af3
--- /dev/null
+++ b/packages/hub-ui-onboard/vite.client.config.ts
@@ -0,0 +1,20 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+
+/**
+ * The stand-in floating button: one self-contained ES module served at
+ * `<base>embedded.js`, the same URL the hub serves its own bootstrap from,
+ * so a host injects one script tag and either file answers. Styles live in
+ * the shadow root (`.generated/css.ts`), so no CSS asset is emitted.
+ */
+export default defineConfig({
+  build: {
+    outDir: fileURLToPath(new URL('./dist/client', import.meta.url)),
+    emptyOutDir: false,
+    lib: {
+      entry: fileURLToPath(new URL('./src/client/index.ts', import.meta.url)),
+      formats: ['es'],
+      fileName: () => 'embedded.js',
+    },
+  },
+})
diff --git a/packages/hub-ui-onboard/vitest.config.ts b/packages/hub-ui-onboard/vitest.config.ts
new file mode 100644
index 00000000..aa0870e8
--- /dev/null
+++ b/packages/hub-ui-onboard/vitest.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    name: '@devframes/hub-ui-onboard',
+    // The install test runs a real package manager.
+    testTimeout: 120_000,
+  },
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d78240fd..ae63843e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -276,6 +276,9 @@ catalogs:
     p-limit:
       specifier: ^7.3.3
       version: 7.3.3
+    package-manager-detector:
+      specifier: ^1.8.0
+      version: 1.8.0
     parse5:
       specifier: ^8.0.1
       version: 8.0.1
@@ -558,6 +561,7 @@ overrides:
   '@devframes/agentic': workspace:*
   '@devframes/hub': workspace:*
   '@devframes/hub-ui': workspace:*
+  '@devframes/hub-ui-onboard': workspace:*
   '@devframes/json-render': workspace:*
   '@devframes/json-render-ui': workspace:*
   '@devframes/next': workspace:*
@@ -1267,6 +1271,18 @@ importers:
         specifier: catalog:types
         version: 26.6.4
 
+  examples/hub-onboard-vite:
+    devDependencies:
+      '@devframes/hub-ui-onboard':
+        specifier: workspace:*
+        version: link:../../packages/hub-ui-onboard
+      '@types/node':
+        specifier: catalog:types
+        version: 26.6.4
+      vite:
+        specifier: catalog:build
+        version: 8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(terser@5.47.1)(tsx@4.23.15)(yaml@2.9.1)
+
   examples/hub-rsbuild:
     dependencies:
       '@devframes/hub':
@@ -1789,6 +1805,37 @@ importers:
         specifier: catalog:frontend
         version: 0.2.0(vue@3.5.43(typescript@6.0.3))
 
+  packages/hub-ui-onboard:
+    dependencies:
+      nostics:
+        specifier: catalog:deps
+        version: 1.3.0
+      package-manager-detector:
+        specifier: catalog:deps
+        version: 1.8.0
+      tinyexec:
+        specifier: catalog:deps
+        version: 1.3.1
+    devDependencies:
+      '@types/node':
+        specifier: catalog:types
+        version: 26.6.4
+      tsdown:
+        specifier: catalog:build
+        version: 0.23.0(@volar/typescript@2.4.28(typescript@6.0.3))(oxc-resolver@11.24.2)(tsx@4.23.15)(typescript@6.0.3)
+      tsx:
+        specifier: catalog:build
+        version: 4.23.15
+      unocss:
+        specifier: ^66.10.5
+        version: 66.10.5(@unocss/postcss@66.10.5(postcss@8.5.28))(rolldown@1.2.12)(rollup@4.60.3)(vite@8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(terser@5.47.1)(tsx@4.23.15)(yaml@2.9.1))
+      vite:
+        specifier: catalog:build
+        version: 8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(terser@5.47.1)(tsx@4.23.15)(yaml@2.9.1)
+      vitest:
+        specifier: catalog:testing
+        version: 5.0.3(@opentelemetry/api@1.9.1)(@types/node@26.6.4)(vite@8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(terser@5.47.1)(tsx@4.23.15)(yaml@2.9.1))
+
   packages/json-render:
     dependencies:
       '@json-render/core':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 347c9672..8e34a9ab 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -57,6 +57,7 @@ overrides:
   '@devframes/agentic': 'workspace:*'
   '@devframes/hub': 'workspace:*'
   '@devframes/hub-ui': 'workspace:*'
+  '@devframes/hub-ui-onboard': 'workspace:*'
   '@devframes/json-render': 'workspace:*'
   '@devframes/json-render-ui': 'workspace:*'
   '@devframes/next': 'workspace:*'
@@ -141,6 +142,7 @@ catalogs:
     obug: ^3.0.0
     ohash: ^2.0.12
     p-limit: ^7.3.3
+    package-manager-detector: ^1.8.0
     parse5: ^8.0.1
     pathe: ^2.0.3
     perfect-debounce: ^2.1.0
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
new file mode 100644
index 00000000..5b9e8132
--- /dev/null
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
@@ -0,0 +1,60 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@devframes/hub-ui-onboard`
+ */
+// #region Interfaces
+export interface CreateOnboardingOptions {
+  packages: string[];
+  base?: string;
+  cwd?: string;
+  stateDir?: string;
+  dev?: boolean;
+  branding?: OnboardingBranding;
+  messages?: Partial<OnboardingMessages>;
+  onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>;
+}
+export interface Onboarding {
+  handler: OnboardingHandler;
+  nodeMiddleware: (_: import('node:http').IncomingMessage, _: import('node:http').ServerResponse, _?: (_?: unknown) => void) => void;
+  disabled: boolean;
+  installed: boolean;
+  scriptSrc: string;
+}
+export interface OnboardingBranding {
+  productName?: string;
+  logo?: OnboardingLogo;
+  primaryColor?: string;
+}
+export interface OnboardingMessages {
+  title: string;
+  description: string;
+  install: string;
+  hide: string;
+  disable: string;
+  installing: string;
+  restart: string;
+  retry: string;
+}
+export interface OnboardingStatus {
+  state: OnboardingState;
+  command: string;
+  branding: OnboardingBranding;
+  messages: OnboardingMessages;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+// #endregion
+
+// #region Types
+export type OnboardingHandler = (_: Request) => Response | Promise<Response>;
+export type OnboardingLogo = string | {
+  light: string;
+  dark?: string;
+};
+export type OnboardingState = 'idle' | 'installing' | 'installed' | 'ready' | 'error' | 'disabled';
+// #endregion
+
+// #region Functions
+export declare function createOnboarding(_: CreateOnboardingOptions): Onboarding;
+// #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.js
new file mode 100644
index 00000000..b9fa2f66
--- /dev/null
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.js
@@ -0,0 +1,6 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@devframes/hub-ui-onboard`
+ */
+// #region Functions
+export function createOnboarding(_) {}
+// #endregion
\ No newline at end of file
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 4839e92a..493cf3fe 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -166,6 +166,9 @@
       "@devframes/hub-ui": [
         "./packages/hub-ui/src/index.ts"
       ],
+      "@devframes/hub-ui-onboard": [
+        "./packages/hub-ui-onboard/src/index.ts"
+      ],
       "@devframes/nuxt/runtime/plugin.client": [
         "./packages/nuxt/src/runtime/plugin.client.ts"
       ],
diff --git a/turbo.json b/turbo.json
index 25b87951..163823e8 100644
--- a/turbo.json
+++ b/turbo.json
@@ -3,7 +3,7 @@
   "globalDependencies": ["pnpm-lock.yaml", "tsconfig.base.json"],
   "tasks": {
     "typecheck": {
-      "dependsOn": ["^typecheck", "@devframes/hub-ui#build:css", "@devframes/json-render-ui#build:css"]
+      "dependsOn": ["^typecheck", "@devframes/hub-ui#build:css", "@devframes/hub-ui-onboard#build:css", "@devframes/json-render-ui#build:css"]
     },
     // `devframe` ⇄ `@devframes/agentic` are circular in the package graph
     // (agentic peers on devframe; devframe devDeps agentic so tests can
@@ -20,6 +20,10 @@
       "outputLogs": "new-only",
       "outputs": ["src/client/.generated/**"]
     },
+    "@devframes/hub-ui-onboard#build:css": {
+      "outputLogs": "new-only",
+      "outputs": ["src/client/.generated/**"]
+    },
     "@devframes/json-render-ui#build:css": {
       "outputLogs": "new-only",
       "outputs": ["src/.generated/**"]
@@ -63,6 +67,11 @@
       "dependsOn": ["devframe#build", "@devframes/hub#build"],
       "outputs": ["dist/**"]
     },
+    "@devframes/hub-ui-onboard#build": {
+      "outputLogs": "new-only",
+      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/design/**"],
+      "outputs": ["dist/**"]
+    },
     "@devframes/json-render-ui#build": {
       "outputLogs": "new-only",
       "dependsOn": ["@devframes/json-render#build", "@devframes/vite#build"],
diff --git a/vitest.config.ts b/vitest.config.ts
index 8d4eaad5..5c51ea2f 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -17,6 +17,7 @@ export default defineConfig({
       'packages/devframe',
       'packages/hub',
       'packages/hub-ui',
+      'packages/hub-ui-onboard',
       'packages/json-render',
       'packages/json-render-ui',
       'plugins/code-server',