From d765770f6f3e8823103c8d4c86abe58ca8c1d752 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 27 Aug 2026 02:22:25 +0000
Subject: [PATCH 1/7] docs: add an interactive Getting Started wizard to the
 guide

Adds a checkbox-based questionnaire (data source, target environments,
data availability, frontend approach, agent support, and other
requirements) that recommends a tailored reading list from the guide,
adapters, frameworks, and plugins docs. Selections persist to
localStorage so a reader can leave and come back to the page.
---
 docs/app/app.config.ts                        |   1 +
 .../global/GettingStartedWizard.vue           | 273 ++++++++++++++++++
 docs/content/1.guide/0.getting-started.md     |  11 +
 docs/content/1.guide/index.md                 |   2 +
 4 files changed, 287 insertions(+)
 create mode 100644 docs/app/components/global/GettingStartedWizard.vue
 create mode 100644 docs/content/1.guide/0.getting-started.md

diff --git a/docs/app/app.config.ts b/docs/app/app.config.ts
index 62a33626..f42ff721 100644
--- a/docs/app/app.config.ts
+++ b/docs/app/app.config.ts
@@ -74,6 +74,7 @@ export default defineAppConfig({
           title: 'Introduction',
           items: [
             '/guide',
+            '/guide/getting-started',
             '/guide/tutorial-server-data-inspector',
           ],
         },
diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
new file mode 100644
index 00000000..384ed625
--- /dev/null
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -0,0 +1,273 @@
+<script setup lang="ts">
+/**
+ * Interactive "what should I read" wizard for the Getting Started guide.
+ *
+ * Every question is a checkbox group (multiple answers allowed per question,
+ * since a real devtool usually spans more than one answer — e.g. it reads
+ * from both the node side and the user's web app). Selections persist to
+ * `localStorage` so a reader can leave the page and pick up where they left
+ * off; the recommended reading list at the bottom recomputes from whatever
+ * is currently checked.
+ */
+
+interface WizardItem {
+  value: string
+  label: string
+  description?: string
+}
+
+interface WizardSection {
+  key: string
+  legend: string
+  items: WizardItem[]
+}
+
+interface DocEntry {
+  title: string
+  description: string
+  icon: string
+}
+
+const STORAGE_KEY = 'devframe-docs:getting-started'
+
+const sections: WizardSection[] = [
+  {
+    key: 'dataSource',
+    legend: 'Where do you want to visualize data from?',
+    items: [
+      { value: 'node', label: 'The node side', description: 'Server state, build output, the filesystem, child processes' },
+      { value: 'browser', label: 'The user\'s web app', description: 'State living in the page you\'re developing' },
+    ],
+  },
+  {
+    key: 'environments',
+    legend: 'What do you expect your tool to work with?',
+    items: [
+      { value: 'standalone', label: 'Standalone', description: 'A CLI or dev server with no host framework' },
+      { value: 'vite', label: 'Vite' },
+      { value: 'next', label: 'Next.js' },
+      { value: 'framework', label: 'A specific framework', description: 'Nuxt, or a host framework the kits don\'t cover yet' },
+      { value: 'all', label: 'All frameworks', description: 'Anything that speaks a Web Standard Request/Response' },
+    ],
+  },
+  {
+    key: 'availability',
+    legend: 'When is the data available?',
+    items: [
+      { value: 'dev', label: 'Development time', description: 'Live, over a running dev server' },
+      { value: 'build', label: 'Production build time' },
+      { value: 'static', label: 'Statically available', description: 'Local filesystem, a static dump, etc.' },
+      { value: 'remote', label: 'Remotely', description: 'Over the web, not on localhost' },
+    ],
+  },
+  {
+    key: 'frontend',
+    legend: 'How do you want to build the frontend view?',
+    items: [
+      { value: 'framework', label: 'A preferred framework', description: 'Vue, React, Svelte, Solid...' },
+      { value: 'webcomponents', label: 'Web Components' },
+      { value: 'nodeside', label: 'Build the frontend on the node side', description: 'Describe the UI as data instead of shipping a bundle' },
+    ],
+  },
+  {
+    key: 'agent',
+    legend: 'Should it also work with a coding agent?',
+    items: [
+      { value: 'agent', label: 'Yes, expose it to a coding agent', description: 'Same RPC functions, resources, and state, over MCP' },
+    ],
+  },
+  {
+    key: 'requirements',
+    legend: 'Any specific requirements?',
+    items: [
+      { value: 'streaming', label: 'Streaming data' },
+      { value: 'overlay', label: 'An overlay on the user\'s web app' },
+      { value: 'hub', label: 'Composing with other devtools', description: 'One UI, many devframes' },
+      { value: 'security', label: 'Authentication' },
+      { value: 'deep-linking', label: 'Deep linking', description: 'Shareable URLs into a specific view' },
+      { value: 'terminal', label: 'Terminal / process access' },
+    ],
+  },
+]
+
+/** Every doc a recommendation can point at, keyed by its route. */
+const DOC_CATALOG: Record<string, DocEntry> = {
+  '/guide': { title: 'Introduction', description: 'What devframe is and who it\'s for.', icon: 'i-lucide-book-open' },
+  '/guide/devframe-definition': { title: 'Devframe Definition', description: 'One defineDevframe() call returns a portable definition every adapter consumes.', icon: 'i-lucide-package' },
+  '/guide/tutorial-server-data-inspector': { title: 'Tutorial: Build a Server Data Inspector', description: 'Build a devtool end to end, then ship it as a hub dock, a static build, a dev server, and a CLI.', icon: 'i-lucide-graduation-cap' },
+  '/guide/rpc': { title: 'RPC', description: 'Type-safe, bidirectional calls between the node side and the browser side.', icon: 'i-lucide-cable' },
+  '/guide/shared-state': { title: 'Shared State', description: 'Observable state synced between the node side and every RPC client.', icon: 'i-lucide-refresh-cw' },
+  '/guide/streaming': { title: 'Streaming', description: 'Push chunk-style data from the node side to the browser side.', icon: 'i-lucide-radio' },
+  '/guide/client-assets': { title: 'Client Assets', description: 'Where a devframe\'s built SPA lives — a local directory or an npm package.', icon: 'i-lucide-folder-tree' },
+  '/guide/client': { title: 'Client', description: 'Connects any surface to a devframe\'s node side with RPC and shared state.', icon: 'i-lucide-plug' },
+  '/guide/transports': { title: 'Transports', description: 'Live RPC over WebSocket or SSE, transparent to your RPC code.', icon: 'i-lucide-waypoints' },
+  '/guide/security': { title: 'Security', description: 'Localhost binding and a trust handshake before a browser can call RPC.', icon: 'i-lucide-shield-check' },
+  '/guide/agent-native': { title: 'Agent-Native Devframe', description: 'Expose RPC functions, resources, and shared state to coding agents over MCP.', icon: 'i-lucide-bot' },
+  '/guide/hub': { title: 'Hub', description: 'Orchestrate many devtools sharing one UI — docks, terminals, messages, commands.', icon: 'i-lucide-layout-dashboard' },
+  '/guide/client-context': { title: 'Client Scripts & Client Context', description: 'How a dock client script runs a devframe\'s code inside the host page.', icon: 'i-lucide-code-2' },
+  '/guide/hub-initiate': { title: 'Serve a Hub Anywhere', description: 'initHub() serves a whole multi-devframe install from one handler.', icon: 'i-lucide-server-cog' },
+  '/guide/services': { title: 'Cross-Devframe Services', description: 'Expose a typed, namespaced capability to every devframe in a hub.', icon: 'i-lucide-share-2' },
+  '/guide/deep-linking': { title: 'Deep Linking', description: 'Send a user to a specific view inside a devframe from a URL or an agent.', icon: 'i-lucide-link' },
+  '/guide/json-render': { title: 'JSON-Render', description: 'Describe a UI as data — a serializable component spec any frontend renders.', icon: 'i-lucide-braces' },
+  '/guide/build-your-own-json-render-frontend': { title: 'Build Your Own JSON-Render Frontend', description: 'Implement the renderer contract in your own framework instead of the reference one.', icon: 'i-lucide-component' },
+  '/guide/build-your-own-hub-ui': { title: 'Build Your Own Hub UI', description: 'The two contracts a hub UI provider implements — node side and browser side.', icon: 'i-lucide-layout-panel-left' },
+  '/guide/standalone-cli': { title: 'Standalone CLI with Devframe', description: 'npx my-tool starts a dev server serving your SPA over type-safe RPC.', icon: 'i-lucide-terminal' },
+  '/helpers/interactive-auth': { title: 'Interactive Auth', description: 'An OTP auth layer over devframe\'s node-side primitives.', icon: 'i-lucide-key-round' },
+  '/helpers/utilities': { title: 'Utilities', description: 'Small, stable helpers bundled into devframe — no npm install.', icon: 'i-lucide-wrench' },
+  '/adapters': { title: 'Adapters', description: 'Every path from a DevframeDefinition to a running devframe.', icon: 'i-lucide-shuffle' },
+  '/adapters/initiate': { title: 'The Standard Handler', description: 'initDevframe() turns a definition into a Web Standard Request → Response handler.', icon: 'i-lucide-server' },
+  '/adapters/cac': { title: 'CLI (cac)', description: 'A cac CLI around a DevframeDefinition with dev, build, and mcp commands.', icon: 'i-lucide-square-terminal' },
+  '/adapters/build': { title: 'Build', description: 'Produces a static deploy of a devframe.', icon: 'i-lucide-hammer' },
+  '/adapters/vite': { title: 'Vite (adapter)', description: 'Wraps a definition so Vite DevTools\' plugin-scan picks it up.', icon: 'i-lucide-zap' },
+  '/adapters/embedded': { title: 'Embedded', description: 'Register a devframe into an already-running context at runtime.', icon: 'i-lucide-plug-zap' },
+  '/adapters/mcp': { title: 'MCP', description: 'Exposes a devframe\'s agent-facing API as a Model Context Protocol server.', icon: 'i-lucide-bot' },
+  '/frameworks': { title: 'Frameworks', description: 'Framework kits that integrate devframe with a meta-framework\'s dev server.', icon: 'i-lucide-blocks' },
+  '/frameworks/vite': { title: 'Vite', description: 'Author one devframe\'s SPA, or mount a whole hub, from a Vite plugin.', icon: 'i-simple-icons-vite' },
+  '/frameworks/next': { title: 'Next', description: 'Host devframes from a Next.js App Router app via a route handler.', icon: 'i-simple-icons-nextdotjs' },
+  '/frameworks/nuxt': { title: 'Nuxt', description: 'A Nuxt module split into authoring one devframe or mounting a hub.', icon: 'i-simple-icons-nuxtdotjs' },
+  '/plugins/a11y': { title: 'Accessibility Inspector', description: 'Runs axe-core against the user app and highlights violations in the page.', icon: 'i-lucide-accessibility' },
+  '/plugins/terminals': { title: 'Terminals', description: 'A terminal panel built on xterm.js.', icon: 'i-lucide-square-terminal' },
+}
+
+/** Always worth reading, regardless of what's checked above. */
+const BASE_DOCS = ['/guide', '/guide/devframe-definition', '/guide/tutorial-server-data-inspector']
+
+/** `${section.key}:${item.value}` -> doc routes that answer is worth reading. */
+const RECOMMENDATIONS: Record<string, string[]> = {
+  'dataSource:node': ['/guide/rpc', '/guide/shared-state', '/helpers/utilities'],
+  'dataSource:browser': ['/guide/client-context', '/guide/deep-linking', '/plugins/a11y'],
+
+  'environments:standalone': ['/guide/standalone-cli', '/adapters/cac', '/adapters/build'],
+  'environments:vite': ['/frameworks/vite', '/adapters/vite'],
+  'environments:next': ['/frameworks/next'],
+  'environments:framework': ['/frameworks/nuxt', '/adapters/embedded'],
+  'environments:all': ['/adapters/initiate', '/adapters', '/guide/devframe-definition'],
+
+  'availability:dev': ['/guide/rpc', '/guide/transports'],
+  'availability:build': ['/adapters/build', '/guide/client-assets'],
+  'availability:static': ['/adapters/build', '/helpers/utilities'],
+  'availability:remote': ['/guide/transports', '/guide/security'],
+
+  'frontend:framework': ['/guide/client-assets', '/guide/client'],
+  'frontend:webcomponents': ['/guide/hub', '/guide/build-your-own-hub-ui'],
+  'frontend:nodeside': ['/guide/json-render', '/guide/build-your-own-json-render-frontend'],
+
+  'agent:agent': ['/guide/agent-native', '/adapters/mcp'],
+
+  'requirements:streaming': ['/guide/streaming'],
+  'requirements:overlay': ['/guide/client-context', '/plugins/a11y'],
+  'requirements:hub': ['/guide/hub', '/guide/hub-initiate', '/guide/services'],
+  'requirements:security': ['/guide/security', '/helpers/interactive-auth'],
+  'requirements:deep-linking': ['/guide/deep-linking'],
+  'requirements:terminal': ['/plugins/terminals'],
+}
+
+const selections = reactive<Record<string, string[]>>(
+  Object.fromEntries(sections.map(section => [section.key, [] as string[]])),
+)
+
+onMounted(() => {
+  if (!import.meta.client)
+    return
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw)
+      return
+    const saved = JSON.parse(raw) as Record<string, unknown>
+    for (const section of sections) {
+      const values = saved[section.key]
+      if (!Array.isArray(values))
+        continue
+      const known = new Set(section.items.map(item => item.value))
+      selections[section.key] = values.filter((value): value is string => typeof value === 'string' && known.has(value))
+    }
+  }
+  catch {
+    // Corrupt or inaccessible storage - fall back to a clean slate.
+  }
+})
+
+watch(selections, (value) => {
+  if (!import.meta.client)
+    return
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
+}, { deep: true })
+
+const hasSelections = computed(() => sections.some(section => selections[section.key].length > 0))
+
+const recommendedDocs = computed(() => {
+  const paths = new Set(BASE_DOCS)
+  for (const section of sections) {
+    for (const value of selections[section.key]) {
+      for (const path of RECOMMENDATIONS[`${section.key}:${value}`] ?? [])
+        paths.add(path)
+    }
+  }
+  return [...paths]
+    .filter(path => path in DOC_CATALOG)
+    .map(path => ({ path, ...DOC_CATALOG[path]! }))
+})
+
+function reset() {
+  for (const section of sections) selections[section.key] = []
+}
+</script>
+
+<template>
+  <div class="not-prose rounded-xl border border-default divide-y divide-default overflow-hidden">
+    <div class="flex items-center justify-between gap-4 px-5 py-4 bg-muted">
+      <div>
+        <p class="font-medium text-highlighted">
+          What kind of devtool do you want to build?
+        </p>
+        <p class="text-sm text-muted mt-0.5">
+          Check whatever applies — answers save in your browser.
+        </p>
+      </div>
+      <UButton
+        label="Reset"
+        icon="i-lucide-rotate-ccw"
+        color="neutral"
+        variant="ghost"
+        size="xs"
+        :disabled="!hasSelections"
+        class="cursor-pointer shrink-0"
+        @click="reset"
+      />
+    </div>
+
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-px bg-default">
+      <div
+        v-for="section in sections"
+        :key="section.key"
+        class="bg-default p-5"
+      >
+        <UCheckboxGroup
+          v-model="selections[section.key]"
+          :legend="section.legend"
+          :items="section.items"
+          :ui="{ legend: 'text-base font-medium text-highlighted mb-3' }"
+        />
+      </div>
+    </div>
+
+    <div class="p-5 bg-muted">
+      <p class="font-medium text-highlighted mb-3">
+        {{ hasSelections ? 'Recommended docs, based on your answers' : 'Start here' }}
+      </p>
+      <UPageList divide>
+        <UPageCard
+          v-for="doc in recommendedDocs"
+          :key="doc.path"
+          :to="doc.path"
+          :icon="doc.icon"
+          :title="doc.title"
+          :description="doc.description"
+          orientation="horizontal"
+          variant="ghost"
+          :ui="{ container: 'p-3 sm:p-3', leadingIcon: 'size-5' }"
+        />
+      </UPageList>
+    </div>
+  </div>
+</template>
diff --git a/docs/content/1.guide/0.getting-started.md b/docs/content/1.guide/0.getting-started.md
new file mode 100644
index 00000000..a1a7ebef
--- /dev/null
+++ b/docs/content/1.guide/0.getting-started.md
@@ -0,0 +1,11 @@
+---
+title: 'Getting Started'
+description: 'Answer a few questions about the devtool you want to build and get a reading list tailored to it.'
+---
+
+Every devframe capability lives in its own guide page, so it helps to know which ones apply to what you're building before diving in. Check whatever describes your devtool below, and the list at the bottom updates with the docs worth reading first — your answers are saved in your browser, so you can come back to this page later.
+
+::getting-started-wizard
+::
+
+None of this is a required reading order. [`defineDevframe()`](/guide/devframe-definition) and [the tutorial](/guide/tutorial-server-data-inspector) are worth reading regardless of your answers above — everything else is additive.
diff --git a/docs/content/1.guide/index.md b/docs/content/1.guide/index.md
index 28065319..afd39123 100644
--- a/docs/content/1.guide/index.md
+++ b/docs/content/1.guide/index.md
@@ -19,6 +19,8 @@ Devframe moves that boundary. A capability is defined once against a stable inte
 
 With a coding agent to scaffold the boilerplate, Devframe is also a fast foundation for standing up a bespoke, specific-need, or even one-off devtool.
 
+New here? [Answer a few questions about your devtool](/guide/getting-started) and get a reading list tailored to it.
+
 ## One definition, one standard handler
 
 Every devframe starts with [`defineDevframe()`](/guide/devframe-definition), pairing a tool's identity with its capabilities.

From 99b7d07934597083c07f8ecb13dd4ce3f9c4f03a Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 27 Aug 2026 02:44:22 +0000
Subject: [PATCH 2/7] docs: redesign the getting-started wizard as icon cards

Replace the plain checkbox list with a grid of selectable cards - each
with an icon badge, title, and description - matching the card-picker
pattern used elsewhere for this kind of preference UI. Selected cards
get a highlighted border, tinted icon badge, and a check mark.
---
 .../global/GettingStartedWizard.vue           | 157 ++++++++++++------
 1 file changed, 105 insertions(+), 52 deletions(-)

diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
index 384ed625..f3a9ca29 100644
--- a/docs/app/components/global/GettingStartedWizard.vue
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -2,23 +2,25 @@
 /**
  * Interactive "what should I read" wizard for the Getting Started guide.
  *
- * Every question is a checkbox group (multiple answers allowed per question,
- * since a real devtool usually spans more than one answer — e.g. it reads
- * from both the node side and the user's web app). Selections persist to
- * `localStorage` so a reader can leave the page and pick up where they left
- * off; the recommended reading list at the bottom recomputes from whatever
- * is currently checked.
+ * Every question is a grid of selectable cards (multiple answers allowed per
+ * question, since a real devtool usually spans more than one answer — e.g.
+ * it reads from both the node side and the user's web app). Selections
+ * persist to `localStorage` so a reader can leave the page and pick up where
+ * they left off; the recommended reading list at the bottom recomputes from
+ * whatever is currently checked.
  */
 
 interface WizardItem {
   value: string
   label: string
+  icon: string
   description?: string
 }
 
 interface WizardSection {
   key: string
-  legend: string
+  title: string
+  hint: string
   items: WizardItem[]
 }
 
@@ -33,59 +35,65 @@ const STORAGE_KEY = 'devframe-docs:getting-started'
 const sections: WizardSection[] = [
   {
     key: 'dataSource',
-    legend: 'Where do you want to visualize data from?',
+    title: 'Data source',
+    hint: 'Where do you want to visualize data from?',
     items: [
-      { value: 'node', label: 'The node side', description: 'Server state, build output, the filesystem, child processes' },
-      { value: 'browser', label: 'The user\'s web app', description: 'State living in the page you\'re developing' },
+      { value: 'node', label: 'The node side', icon: 'i-lucide-server', description: 'Server state, build output, the filesystem, child processes' },
+      { value: 'browser', label: 'The user\'s web app', icon: 'i-lucide-app-window', description: 'State living in the page you\'re developing' },
     ],
   },
   {
     key: 'environments',
-    legend: 'What do you expect your tool to work with?',
+    title: 'Target environments',
+    hint: 'What do you expect your tool to work with?',
     items: [
-      { value: 'standalone', label: 'Standalone', description: 'A CLI or dev server with no host framework' },
-      { value: 'vite', label: 'Vite' },
-      { value: 'next', label: 'Next.js' },
-      { value: 'framework', label: 'A specific framework', description: 'Nuxt, or a host framework the kits don\'t cover yet' },
-      { value: 'all', label: 'All frameworks', description: 'Anything that speaks a Web Standard Request/Response' },
+      { value: 'standalone', label: 'Standalone', icon: 'i-lucide-terminal', description: 'A CLI or dev server with no host framework' },
+      { value: 'vite', label: 'Vite', icon: 'i-simple-icons-vite' },
+      { value: 'next', label: 'Next.js', icon: 'i-simple-icons-nextdotjs' },
+      { value: 'framework', label: 'A specific framework', icon: 'i-lucide-puzzle', description: 'Nuxt, or a host framework the kits don\'t cover yet' },
+      { value: 'all', label: 'All frameworks', icon: 'i-lucide-infinity', description: 'Anything that speaks a Web Standard Request/Response' },
     ],
   },
   {
     key: 'availability',
-    legend: 'When is the data available?',
+    title: 'Data availability',
+    hint: 'When is the data available?',
     items: [
-      { value: 'dev', label: 'Development time', description: 'Live, over a running dev server' },
-      { value: 'build', label: 'Production build time' },
-      { value: 'static', label: 'Statically available', description: 'Local filesystem, a static dump, etc.' },
-      { value: 'remote', label: 'Remotely', description: 'Over the web, not on localhost' },
+      { value: 'dev', label: 'Development time', icon: 'i-lucide-code', description: 'Live, over a running dev server' },
+      { value: 'build', label: 'Production build time', icon: 'i-lucide-hammer' },
+      { value: 'static', label: 'Statically available', icon: 'i-lucide-hard-drive', description: 'Local filesystem, a static dump, etc.' },
+      { value: 'remote', label: 'Remotely', icon: 'i-lucide-cloud', description: 'Over the web, not on localhost' },
     ],
   },
   {
     key: 'frontend',
-    legend: 'How do you want to build the frontend view?',
+    title: 'Frontend approach',
+    hint: 'How do you want to build the frontend view?',
     items: [
-      { value: 'framework', label: 'A preferred framework', description: 'Vue, React, Svelte, Solid...' },
-      { value: 'webcomponents', label: 'Web Components' },
-      { value: 'nodeside', label: 'Build the frontend on the node side', description: 'Describe the UI as data instead of shipping a bundle' },
+      { value: 'framework', label: 'A preferred framework', icon: 'i-lucide-component', description: 'Vue, React, Svelte, Solid...' },
+      { value: 'webcomponents', label: 'Web Components', icon: 'i-lucide-box' },
+      { value: 'nodeside', label: 'Build it on the node side', icon: 'i-lucide-braces', description: 'Describe the UI as data instead of shipping a bundle' },
     ],
   },
   {
     key: 'agent',
-    legend: 'Should it also work with a coding agent?',
+    title: 'Agent support',
+    hint: 'Should it also work with a coding agent?',
     items: [
-      { value: 'agent', label: 'Yes, expose it to a coding agent', description: 'Same RPC functions, resources, and state, over MCP' },
+      { value: 'agent', label: 'Yes, expose it to a coding agent', icon: 'i-lucide-bot', description: 'Same RPC functions, resources, and state, over MCP' },
     ],
   },
   {
     key: 'requirements',
-    legend: 'Any specific requirements?',
+    title: 'Other requirements',
+    hint: 'Any specific requirements?',
     items: [
-      { value: 'streaming', label: 'Streaming data' },
-      { value: 'overlay', label: 'An overlay on the user\'s web app' },
-      { value: 'hub', label: 'Composing with other devtools', description: 'One UI, many devframes' },
-      { value: 'security', label: 'Authentication' },
-      { value: 'deep-linking', label: 'Deep linking', description: 'Shareable URLs into a specific view' },
-      { value: 'terminal', label: 'Terminal / process access' },
+      { value: 'streaming', label: 'Streaming data', icon: 'i-lucide-radio' },
+      { value: 'overlay', label: 'An overlay on the user\'s web app', icon: 'i-lucide-layers' },
+      { value: 'hub', label: 'Composing with other devtools', icon: 'i-lucide-layout-dashboard', description: 'One UI, many devframes' },
+      { value: 'security', label: 'Authentication', icon: 'i-lucide-shield-check' },
+      { value: 'deep-linking', label: 'Deep linking', icon: 'i-lucide-link', description: 'Shareable URLs into a specific view' },
+      { value: 'terminal', label: 'Terminal / process access', icon: 'i-lucide-square-terminal' },
     ],
   },
 ]
@@ -104,7 +112,7 @@ const DOC_CATALOG: Record<string, DocEntry> = {
   '/guide/security': { title: 'Security', description: 'Localhost binding and a trust handshake before a browser can call RPC.', icon: 'i-lucide-shield-check' },
   '/guide/agent-native': { title: 'Agent-Native Devframe', description: 'Expose RPC functions, resources, and shared state to coding agents over MCP.', icon: 'i-lucide-bot' },
   '/guide/hub': { title: 'Hub', description: 'Orchestrate many devtools sharing one UI — docks, terminals, messages, commands.', icon: 'i-lucide-layout-dashboard' },
-  '/guide/client-context': { title: 'Client Scripts & Client Context', description: 'How a dock client script runs a devframe\'s code inside the host page.', icon: 'i-lucide-code-2' },
+  '/guide/client-context': { title: 'Client Scripts & Client Context', description: 'How a dock client script runs a devframe\'s code inside the host page.', icon: 'i-lucide-code' },
   '/guide/hub-initiate': { title: 'Serve a Hub Anywhere', description: 'initHub() serves a whole multi-devframe install from one handler.', icon: 'i-lucide-server-cog' },
   '/guide/services': { title: 'Cross-Devframe Services', description: 'Expose a typed, namespaced capability to every devframe in a hub.', icon: 'i-lucide-share-2' },
   '/guide/deep-linking': { title: 'Deep Linking', description: 'Send a user to a specific view inside a devframe from a URL or an agent.', icon: 'i-lucide-link' },
@@ -193,12 +201,25 @@ watch(selections, (value) => {
   localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
 }, { deep: true })
 
-const hasSelections = computed(() => sections.some(section => selections[section.key].length > 0))
+function isChecked(sectionKey: string, value: string): boolean {
+  return selections[sectionKey]!.includes(value)
+}
+
+function toggle(sectionKey: string, value: string): void {
+  const current = selections[sectionKey]!
+  const index = current.indexOf(value)
+  if (index === -1)
+    current.push(value)
+  else
+    current.splice(index, 1)
+}
+
+const hasSelections = computed(() => sections.some(section => selections[section.key]!.length > 0))
 
 const recommendedDocs = computed(() => {
   const paths = new Set(BASE_DOCS)
   for (const section of sections) {
-    for (const value of selections[section.key]) {
+    for (const value of selections[section.key]!) {
       for (const path of RECOMMENDATIONS[`${section.key}:${value}`] ?? [])
         paths.add(path)
     }
@@ -208,14 +229,14 @@ const recommendedDocs = computed(() => {
     .map(path => ({ path, ...DOC_CATALOG[path]! }))
 })
 
-function reset() {
+function reset(): void {
   for (const section of sections) selections[section.key] = []
 }
 </script>
 
 <template>
   <div class="not-prose rounded-xl border border-default divide-y divide-default overflow-hidden">
-    <div class="flex items-center justify-between gap-4 px-5 py-4 bg-muted">
+    <div class="flex items-center justify-between gap-4 px-5 py-4 sm:px-6 bg-muted">
       <div>
         <p class="font-medium text-highlighted">
           What kind of devtool do you want to build?
@@ -236,22 +257,54 @@ function reset() {
       />
     </div>
 
-    <div class="grid grid-cols-1 md:grid-cols-2 gap-px bg-default">
-      <div
-        v-for="section in sections"
-        :key="section.key"
-        class="bg-default p-5"
-      >
-        <UCheckboxGroup
-          v-model="selections[section.key]"
-          :legend="section.legend"
-          :items="section.items"
-          :ui="{ legend: 'text-base font-medium text-highlighted mb-3' }"
-        />
+    <div
+      v-for="section in sections"
+      :key="section.key"
+      class="p-5 sm:p-6"
+    >
+      <p class="font-medium text-highlighted">
+        {{ section.title }}
+      </p>
+      <p class="text-sm text-muted mt-0.5 mb-4">
+        {{ section.hint }}
+      </p>
+
+      <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+        <button
+          v-for="item in section.items"
+          :key="item.value"
+          type="button"
+          role="checkbox"
+          :aria-checked="isChecked(section.key, item.value)"
+          class="relative flex flex-col items-start gap-3 rounded-lg border p-4 text-left transition-colors cursor-pointer"
+          :class="isChecked(section.key, item.value)
+            ? 'border-primary bg-primary/5 ring-1 ring-primary/30'
+            : 'border-default hover:border-accented hover:bg-elevated/50'"
+          @click="toggle(section.key, item.value)"
+        >
+          <UIcon
+            v-if="isChecked(section.key, item.value)"
+            name="i-lucide-circle-check"
+            class="absolute top-3 right-3 size-4 text-primary"
+          />
+          <span
+            class="inline-flex items-center justify-center size-9 rounded-full transition-colors"
+            :class="isChecked(section.key, item.value) ? 'bg-primary/10 text-primary' : 'bg-elevated text-muted'"
+          >
+            <UIcon :name="item.icon" class="size-4.5" />
+          </span>
+          <span>
+            <span class="block text-sm font-medium text-highlighted pe-4">{{ item.label }}</span>
+            <span
+              v-if="item.description"
+              class="block text-xs text-muted mt-0.5"
+            >{{ item.description }}</span>
+          </span>
+        </button>
       </div>
     </div>
 
-    <div class="p-5 bg-muted">
+    <div class="p-5 sm:p-6 bg-muted">
       <p class="font-medium text-highlighted mb-3">
         {{ hasSelections ? 'Recommended docs, based on your answers' : 'Start here' }}
       </p>

From d08d1e530c1836d18faff2ae44455553697a97cb Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 27 Aug 2026 03:44:39 +0000
Subject: [PATCH 3/7] docs: tighten the getting-started wizard's vertical
 spacing

Lay each card out horizontally (icon beside the label) and put each
section's title and hint on one line, trimming section and card padding
so the whole wizard takes far less vertical space.
---
 .../global/GettingStartedWizard.vue           | 44 ++++++++++---------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
index f3a9ca29..7241613f 100644
--- a/docs/app/components/global/GettingStartedWizard.vue
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -236,7 +236,7 @@ function reset(): void {
 
 <template>
   <div class="not-prose rounded-xl border border-default divide-y divide-default overflow-hidden">
-    <div class="flex items-center justify-between gap-4 px-5 py-4 sm:px-6 bg-muted">
+    <div class="flex items-center justify-between gap-4 px-5 py-3 sm:px-6 bg-muted">
       <div>
         <p class="font-medium text-highlighted">
           What kind of devtool do you want to build?
@@ -260,52 +260,54 @@ function reset(): void {
     <div
       v-for="section in sections"
       :key="section.key"
-      class="p-5 sm:p-6"
+      class="px-5 py-4 sm:px-6"
     >
-      <p class="font-medium text-highlighted">
-        {{ section.title }}
-      </p>
-      <p class="text-sm text-muted mt-0.5 mb-4">
-        {{ section.hint }}
-      </p>
+      <div class="flex flex-wrap items-baseline gap-x-2 mb-3">
+        <p class="font-medium text-highlighted">
+          {{ section.title }}
+        </p>
+        <p class="text-sm text-muted">
+          {{ section.hint }}
+        </p>
+      </div>
 
-      <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+      <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-2.5">
         <button
           v-for="item in section.items"
           :key="item.value"
           type="button"
           role="checkbox"
           :aria-checked="isChecked(section.key, item.value)"
-          class="relative flex flex-col items-start gap-3 rounded-lg border p-4 text-left transition-colors cursor-pointer"
+          class="relative flex items-center gap-3 rounded-lg border p-3 text-left transition-colors cursor-pointer"
           :class="isChecked(section.key, item.value)
             ? 'border-primary bg-primary/5 ring-1 ring-primary/30'
             : 'border-default hover:border-accented hover:bg-elevated/50'"
           @click="toggle(section.key, item.value)"
         >
-          <UIcon
-            v-if="isChecked(section.key, item.value)"
-            name="i-lucide-circle-check"
-            class="absolute top-3 right-3 size-4 text-primary"
-          />
           <span
-            class="inline-flex items-center justify-center size-9 rounded-full transition-colors"
+            class="inline-flex items-center justify-center size-8 shrink-0 rounded-full transition-colors"
             :class="isChecked(section.key, item.value) ? 'bg-primary/10 text-primary' : 'bg-elevated text-muted'"
           >
-            <UIcon :name="item.icon" class="size-4.5" />
+            <UIcon :name="item.icon" class="size-4" />
           </span>
-          <span>
-            <span class="block text-sm font-medium text-highlighted pe-4">{{ item.label }}</span>
+          <span class="min-w-0 flex-1">
+            <span class="block text-sm font-medium text-highlighted">{{ item.label }}</span>
             <span
               v-if="item.description"
               class="block text-xs text-muted mt-0.5"
             >{{ item.description }}</span>
           </span>
+          <UIcon
+            v-if="isChecked(section.key, item.value)"
+            name="i-lucide-circle-check"
+            class="size-4 shrink-0 text-primary"
+          />
         </button>
       </div>
     </div>
 
-    <div class="p-5 sm:p-6 bg-muted">
-      <p class="font-medium text-highlighted mb-3">
+    <div class="px-5 py-4 sm:px-6 bg-muted">
+      <p class="font-medium text-highlighted mb-2">
         {{ hasSelections ? 'Recommended docs, based on your answers' : 'Start here' }}
       </p>
       <UPageList divide>

From 1e017ff4e5abbbdd850f7c480db6faaff4eb505c Mon Sep 17 00:00:00 2001
From: Anthony Fu <github@antfu.me>
Date: Thu, 27 Aug 2026 13:11:49 +0900
Subject: [PATCH 4/7] chore: update

---
 .../global/GettingStartedWizard.vue           | 64 ++++++++-----------
 docs/content/1.guide/0.getting-started.md     |  2 +-
 2 files changed, 26 insertions(+), 40 deletions(-)

diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
index 7241613f..c21888e1 100644
--- a/docs/app/components/global/GettingStartedWizard.vue
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -33,6 +33,16 @@ interface DocEntry {
 const STORAGE_KEY = 'devframe-docs:getting-started'
 
 const sections: WizardSection[] = [
+  {
+    key: 'environments',
+    title: 'Target environments',
+    hint: 'What do you expect your tool to work with?',
+    items: [
+      { value: 'standalone', label: 'Standalone', icon: 'i-lucide-terminal', description: 'A CLI or dev server with no host framework' },
+      { value: 'framework', label: 'Specific framework', icon: 'i-lucide-shapes', description: 'Specifically for frameworks like Vite, Next.js, Nuxt, etc.' },
+      { value: 'all', label: 'All frameworks', icon: 'i-lucide-infinity', description: 'I want to support as many frameworks as possible' },
+    ],
+  },
   {
     key: 'dataSource',
     title: 'Data source',
@@ -42,27 +52,15 @@ const sections: WizardSection[] = [
       { value: 'browser', label: 'The user\'s web app', icon: 'i-lucide-app-window', description: 'State living in the page you\'re developing' },
     ],
   },
-  {
-    key: 'environments',
-    title: 'Target environments',
-    hint: 'What do you expect your tool to work with?',
-    items: [
-      { value: 'standalone', label: 'Standalone', icon: 'i-lucide-terminal', description: 'A CLI or dev server with no host framework' },
-      { value: 'vite', label: 'Vite', icon: 'i-simple-icons-vite' },
-      { value: 'next', label: 'Next.js', icon: 'i-simple-icons-nextdotjs' },
-      { value: 'framework', label: 'A specific framework', icon: 'i-lucide-puzzle', description: 'Nuxt, or a host framework the kits don\'t cover yet' },
-      { value: 'all', label: 'All frameworks', icon: 'i-lucide-infinity', description: 'Anything that speaks a Web Standard Request/Response' },
-    ],
-  },
   {
     key: 'availability',
     title: 'Data availability',
     hint: 'When is the data available?',
     items: [
       { value: 'dev', label: 'Development time', icon: 'i-lucide-code', description: 'Live, over a running dev server' },
-      { value: 'build', label: 'Production build time', icon: 'i-lucide-hammer' },
-      { value: 'static', label: 'Statically available', icon: 'i-lucide-hard-drive', description: 'Local filesystem, a static dump, etc.' },
-      { value: 'remote', label: 'Remotely', icon: 'i-lucide-cloud', description: 'Over the web, not on localhost' },
+      { value: 'build', label: 'Production build time', icon: 'i-lucide-hammer', description: 'Data from the production build' },
+      { value: 'static', label: 'Statically available', icon: 'i-lucide-hard-drive', description: 'Local filesystem, uploaded files, etc.' },
+      { value: 'remote', label: 'Remotely', icon: 'i-lucide-cloud', description: 'Over the web' },
     ],
   },
   {
@@ -71,29 +69,20 @@ const sections: WizardSection[] = [
     hint: 'How do you want to build the frontend view?',
     items: [
       { value: 'framework', label: 'A preferred framework', icon: 'i-lucide-component', description: 'Vue, React, Svelte, Solid...' },
-      { value: 'webcomponents', label: 'Web Components', icon: 'i-lucide-box' },
+      { value: 'webcomponents', label: 'Web Components', icon: 'i-lucide-box', description: 'Use Web Components for renderering' },
       { value: 'nodeside', label: 'Build it on the node side', icon: 'i-lucide-braces', description: 'Describe the UI as data instead of shipping a bundle' },
     ],
   },
-  {
-    key: 'agent',
-    title: 'Agent support',
-    hint: 'Should it also work with a coding agent?',
-    items: [
-      { value: 'agent', label: 'Yes, expose it to a coding agent', icon: 'i-lucide-bot', description: 'Same RPC functions, resources, and state, over MCP' },
-    ],
-  },
   {
     key: 'requirements',
     title: 'Other requirements',
     hint: 'Any specific requirements?',
     items: [
-      { value: 'streaming', label: 'Streaming data', icon: 'i-lucide-radio' },
-      { value: 'overlay', label: 'An overlay on the user\'s web app', icon: 'i-lucide-layers' },
-      { value: 'hub', label: 'Composing with other devtools', icon: 'i-lucide-layout-dashboard', description: 'One UI, many devframes' },
-      { value: 'security', label: 'Authentication', icon: 'i-lucide-shield-check' },
+      { value: 'agent', label: 'Exposed to coding agents', icon: 'i-lucide-bot', description: 'Some functionality should be available to coding agents.' },
+      { value: 'terminal', label: 'Sub process access', icon: 'i-lucide-square-terminal', description: 'Need to spawn other child process from the node side' },
+      { value: 'streaming', label: 'Streaming data', icon: 'i-lucide-radio', description: 'Push chunk-style data from the node side to the browser side' },
       { value: 'deep-linking', label: 'Deep linking', icon: 'i-lucide-link', description: 'Shareable URLs into a specific view' },
-      { value: 'terminal', label: 'Terminal / process access', icon: 'i-lucide-square-terminal' },
+      { value: 'overlay', label: 'User app overlay', icon: 'i-lucide-layers', description: 'I want to overlay a UI on top of the user\'s web app' },
     ],
   },
 ]
@@ -242,7 +231,7 @@ function reset(): void {
           What kind of devtool do you want to build?
         </p>
         <p class="text-sm text-muted mt-0.5">
-          Check whatever applies — answers save in your browser.
+          Multi-select, check whatever applies (selection persists in localStorage)
         </p>
       </div>
       <UButton
@@ -264,14 +253,15 @@ function reset(): void {
     >
       <div class="flex flex-wrap items-baseline gap-x-2 mb-3">
         <p class="font-medium text-highlighted">
-          {{ section.title }}
-        </p>
-        <p class="text-sm text-muted">
           {{ section.hint }}
         </p>
+        <p class="text-xs text-muted uppercase tracking-widest">
+          {{ section.title }}
+        </p>
       </div>
 
       <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-2.5">
+        <!-- Add colors for different items -->
         <button
           v-for="item in section.items"
           :key="item.value"
@@ -280,7 +270,7 @@ function reset(): void {
           :aria-checked="isChecked(section.key, item.value)"
           class="relative flex items-center gap-3 rounded-lg border p-3 text-left transition-colors cursor-pointer"
           :class="isChecked(section.key, item.value)
-            ? 'border-primary bg-primary/5 ring-1 ring-primary/30'
+            ? 'border-primary/80 bg-primary/10 ring-1 ring-primary/20'
             : 'border-default hover:border-accented hover:bg-elevated/50'"
           @click="toggle(section.key, item.value)"
         >
@@ -297,11 +287,6 @@ function reset(): void {
               class="block text-xs text-muted mt-0.5"
             >{{ item.description }}</span>
           </span>
-          <UIcon
-            v-if="isChecked(section.key, item.value)"
-            name="i-lucide-circle-check"
-            class="size-4 shrink-0 text-primary"
-          />
         </button>
       </div>
     </div>
@@ -310,6 +295,7 @@ function reset(): void {
       <p class="font-medium text-highlighted mb-2">
         {{ hasSelections ? 'Recommended docs, based on your answers' : 'Start here' }}
       </p>
+      <!-- TODO: use inline elements, instead UPage -->
       <UPageList divide>
         <UPageCard
           v-for="doc in recommendedDocs"
diff --git a/docs/content/1.guide/0.getting-started.md b/docs/content/1.guide/0.getting-started.md
index a1a7ebef..573c6d07 100644
--- a/docs/content/1.guide/0.getting-started.md
+++ b/docs/content/1.guide/0.getting-started.md
@@ -3,7 +3,7 @@ title: 'Getting Started'
 description: 'Answer a few questions about the devtool you want to build and get a reading list tailored to it.'
 ---
 
-Every devframe capability lives in its own guide page, so it helps to know which ones apply to what you're building before diving in. Check whatever describes your devtool below, and the list at the bottom updates with the docs worth reading first — your answers are saved in your browser, so you can come back to this page later.
+Devframe provides a lot of features to build DevTools with various needs. It could be overwhelming to start with. Here we have the wizard to help you get started. Answer a few questions about the devtool you want to build and get a reading list tailored to it.
 
 ::getting-started-wizard
 ::

From df7730da2acf0d85ae70bad9b1f725bc0463aae0 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 27 Aug 2026 04:33:16 +0000
Subject: [PATCH 5/7] =?UTF-8?q?docs:=20implement=20wizard=20TODOs=20?=
 =?UTF-8?q?=E2=80=94=20per-item=20colors=20and=20inline=20doc=20links?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Give each option its own tinted icon badge via a static color map, and
  restore a check mark for the selected state (the badge no longer carries it).
- Render the recommended-docs list as inline NuxtLink rows instead of
  UPageList/UPageCard.
- Realign the recommendation map with the reworked sections: map the moved
  'agent' item, broaden the merged 'specific framework' option, and drop the
  now-dead keys.
---
 .../global/GettingStartedWizard.vue           | 110 +++++++++++-------
 1 file changed, 69 insertions(+), 41 deletions(-)

diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
index c21888e1..befb7a54 100644
--- a/docs/app/components/global/GettingStartedWizard.vue
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -14,9 +14,32 @@ interface WizardItem {
   value: string
   label: string
   icon: string
+  /** Accent color key from `ICON_COLORS`, giving each item its own tinted badge. */
+  color: keyof typeof ICON_COLORS
   description?: string
 }
 
+/**
+ * Per-item icon badge colors. Spelled out as full class strings (not
+ * interpolated) so Tailwind's scanner keeps them in the build.
+ */
+const ICON_COLORS = {
+  sky: 'bg-sky-500/10 text-sky-500',
+  indigo: 'bg-indigo-500/10 text-indigo-500',
+  violet: 'bg-violet-500/10 text-violet-500',
+  purple: 'bg-purple-500/10 text-purple-500',
+  fuchsia: 'bg-fuchsia-500/10 text-fuchsia-500',
+  pink: 'bg-pink-500/10 text-pink-500',
+  rose: 'bg-rose-500/10 text-rose-500',
+  amber: 'bg-amber-500/10 text-amber-500',
+  orange: 'bg-orange-500/10 text-orange-500',
+  emerald: 'bg-emerald-500/10 text-emerald-500',
+  teal: 'bg-teal-500/10 text-teal-500',
+  cyan: 'bg-cyan-500/10 text-cyan-500',
+  blue: 'bg-blue-500/10 text-blue-500',
+  green: 'bg-green-500/10 text-green-500',
+} as const
+
 interface WizardSection {
   key: string
   title: string
@@ -38,9 +61,9 @@ const sections: WizardSection[] = [
     title: 'Target environments',
     hint: 'What do you expect your tool to work with?',
     items: [
-      { value: 'standalone', label: 'Standalone', icon: 'i-lucide-terminal', description: 'A CLI or dev server with no host framework' },
-      { value: 'framework', label: 'Specific framework', icon: 'i-lucide-shapes', description: 'Specifically for frameworks like Vite, Next.js, Nuxt, etc.' },
-      { value: 'all', label: 'All frameworks', icon: 'i-lucide-infinity', description: 'I want to support as many frameworks as possible' },
+      { value: 'standalone', label: 'Standalone', icon: 'i-lucide-terminal', color: 'sky', description: 'A CLI or dev server with no host framework' },
+      { value: 'framework', label: 'Specific framework', icon: 'i-lucide-shapes', color: 'violet', description: 'Specifically for frameworks like Vite, Next.js, Nuxt, etc.' },
+      { value: 'all', label: 'All frameworks', icon: 'i-lucide-infinity', color: 'emerald', description: 'I want to support as many frameworks as possible' },
     ],
   },
   {
@@ -48,8 +71,8 @@ const sections: WizardSection[] = [
     title: 'Data source',
     hint: 'Where do you want to visualize data from?',
     items: [
-      { value: 'node', label: 'The node side', icon: 'i-lucide-server', description: 'Server state, build output, the filesystem, child processes' },
-      { value: 'browser', label: 'The user\'s web app', icon: 'i-lucide-app-window', description: 'State living in the page you\'re developing' },
+      { value: 'node', label: 'The node side', icon: 'i-lucide-server', color: 'indigo', description: 'Server state, build output, the filesystem, child processes' },
+      { value: 'browser', label: 'The user\'s web app', icon: 'i-lucide-app-window', color: 'cyan', description: 'State living in the page you\'re developing' },
     ],
   },
   {
@@ -57,10 +80,10 @@ const sections: WizardSection[] = [
     title: 'Data availability',
     hint: 'When is the data available?',
     items: [
-      { value: 'dev', label: 'Development time', icon: 'i-lucide-code', description: 'Live, over a running dev server' },
-      { value: 'build', label: 'Production build time', icon: 'i-lucide-hammer', description: 'Data from the production build' },
-      { value: 'static', label: 'Statically available', icon: 'i-lucide-hard-drive', description: 'Local filesystem, uploaded files, etc.' },
-      { value: 'remote', label: 'Remotely', icon: 'i-lucide-cloud', description: 'Over the web' },
+      { value: 'dev', label: 'Development time', icon: 'i-lucide-code', color: 'blue', description: 'Live, over a running dev server' },
+      { value: 'build', label: 'Production build time', icon: 'i-lucide-hammer', color: 'amber', description: 'Data from the production build' },
+      { value: 'static', label: 'Statically available', icon: 'i-lucide-hard-drive', color: 'teal', description: 'Local filesystem, uploaded files, etc.' },
+      { value: 'remote', label: 'Remotely', icon: 'i-lucide-cloud', color: 'sky', description: 'Over the web' },
     ],
   },
   {
@@ -68,9 +91,9 @@ const sections: WizardSection[] = [
     title: 'Frontend approach',
     hint: 'How do you want to build the frontend view?',
     items: [
-      { value: 'framework', label: 'A preferred framework', icon: 'i-lucide-component', description: 'Vue, React, Svelte, Solid...' },
-      { value: 'webcomponents', label: 'Web Components', icon: 'i-lucide-box', description: 'Use Web Components for renderering' },
-      { value: 'nodeside', label: 'Build it on the node side', icon: 'i-lucide-braces', description: 'Describe the UI as data instead of shipping a bundle' },
+      { value: 'framework', label: 'A preferred framework', icon: 'i-lucide-component', color: 'green', description: 'Vue, React, Svelte, Solid...' },
+      { value: 'webcomponents', label: 'Web Components', icon: 'i-lucide-box', color: 'orange', description: 'Use Web Components for renderering' },
+      { value: 'nodeside', label: 'Build it on the node side', icon: 'i-lucide-braces', color: 'purple', description: 'Describe the UI as data instead of shipping a bundle' },
     ],
   },
   {
@@ -78,11 +101,11 @@ const sections: WizardSection[] = [
     title: 'Other requirements',
     hint: 'Any specific requirements?',
     items: [
-      { value: 'agent', label: 'Exposed to coding agents', icon: 'i-lucide-bot', description: 'Some functionality should be available to coding agents.' },
-      { value: 'terminal', label: 'Sub process access', icon: 'i-lucide-square-terminal', description: 'Need to spawn other child process from the node side' },
-      { value: 'streaming', label: 'Streaming data', icon: 'i-lucide-radio', description: 'Push chunk-style data from the node side to the browser side' },
-      { value: 'deep-linking', label: 'Deep linking', icon: 'i-lucide-link', description: 'Shareable URLs into a specific view' },
-      { value: 'overlay', label: 'User app overlay', icon: 'i-lucide-layers', description: 'I want to overlay a UI on top of the user\'s web app' },
+      { value: 'agent', label: 'Exposed to coding agents', icon: 'i-lucide-bot', color: 'pink', description: 'Some functionality should be available to coding agents.' },
+      { value: 'terminal', label: 'Sub process access', icon: 'i-lucide-square-terminal', color: 'amber', description: 'Need to spawn other child process from the node side' },
+      { value: 'streaming', label: 'Streaming data', icon: 'i-lucide-radio', color: 'rose', description: 'Push chunk-style data from the node side to the browser side' },
+      { value: 'deep-linking', label: 'Deep linking', icon: 'i-lucide-link', color: 'cyan', description: 'Shareable URLs into a specific view' },
+      { value: 'overlay', label: 'User app overlay', icon: 'i-lucide-layers', color: 'fuchsia', description: 'I want to overlay a UI on top of the user\'s web app' },
     ],
   },
 ]
@@ -135,9 +158,7 @@ const RECOMMENDATIONS: Record<string, string[]> = {
   'dataSource:browser': ['/guide/client-context', '/guide/deep-linking', '/plugins/a11y'],
 
   'environments:standalone': ['/guide/standalone-cli', '/adapters/cac', '/adapters/build'],
-  'environments:vite': ['/frameworks/vite', '/adapters/vite'],
-  'environments:next': ['/frameworks/next'],
-  'environments:framework': ['/frameworks/nuxt', '/adapters/embedded'],
+  'environments:framework': ['/frameworks/vite', '/frameworks/next', '/frameworks/nuxt', '/adapters/vite', '/adapters/embedded'],
   'environments:all': ['/adapters/initiate', '/adapters', '/guide/devframe-definition'],
 
   'availability:dev': ['/guide/rpc', '/guide/transports'],
@@ -149,14 +170,11 @@ const RECOMMENDATIONS: Record<string, string[]> = {
   'frontend:webcomponents': ['/guide/hub', '/guide/build-your-own-hub-ui'],
   'frontend:nodeside': ['/guide/json-render', '/guide/build-your-own-json-render-frontend'],
 
-  'agent:agent': ['/guide/agent-native', '/adapters/mcp'],
-
+  'requirements:agent': ['/guide/agent-native', '/adapters/mcp'],
+  'requirements:terminal': ['/plugins/terminals'],
   'requirements:streaming': ['/guide/streaming'],
-  'requirements:overlay': ['/guide/client-context', '/plugins/a11y'],
-  'requirements:hub': ['/guide/hub', '/guide/hub-initiate', '/guide/services'],
-  'requirements:security': ['/guide/security', '/helpers/interactive-auth'],
   'requirements:deep-linking': ['/guide/deep-linking'],
-  'requirements:terminal': ['/plugins/terminals'],
+  'requirements:overlay': ['/guide/client-context', '/plugins/a11y'],
 }
 
 const selections = reactive<Record<string, string[]>>(
@@ -261,7 +279,6 @@ function reset(): void {
       </div>
 
       <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-2.5">
-        <!-- Add colors for different items -->
         <button
           v-for="item in section.items"
           :key="item.value"
@@ -275,8 +292,8 @@ function reset(): void {
           @click="toggle(section.key, item.value)"
         >
           <span
-            class="inline-flex items-center justify-center size-8 shrink-0 rounded-full transition-colors"
-            :class="isChecked(section.key, item.value) ? 'bg-primary/10 text-primary' : 'bg-elevated text-muted'"
+            class="inline-flex items-center justify-center size-8 shrink-0 rounded-full"
+            :class="ICON_COLORS[item.color]"
           >
             <UIcon :name="item.icon" class="size-4" />
           </span>
@@ -287,28 +304,39 @@ function reset(): void {
               class="block text-xs text-muted mt-0.5"
             >{{ item.description }}</span>
           </span>
+          <UIcon
+            v-if="isChecked(section.key, item.value)"
+            name="i-lucide-circle-check"
+            class="size-4 shrink-0 text-primary"
+          />
         </button>
       </div>
     </div>
 
     <div class="px-5 py-4 sm:px-6 bg-muted">
-      <p class="font-medium text-highlighted mb-2">
+      <p class="font-medium text-highlighted mb-3">
         {{ hasSelections ? 'Recommended docs, based on your answers' : 'Start here' }}
       </p>
-      <!-- TODO: use inline elements, instead UPage -->
-      <UPageList divide>
-        <UPageCard
+      <div class="flex flex-col divide-y divide-default rounded-lg border border-default overflow-hidden bg-default">
+        <NuxtLink
           v-for="doc in recommendedDocs"
           :key="doc.path"
           :to="doc.path"
-          :icon="doc.icon"
-          :title="doc.title"
-          :description="doc.description"
-          orientation="horizontal"
-          variant="ghost"
-          :ui="{ container: 'p-3 sm:p-3', leadingIcon: 'size-5' }"
-        />
-      </UPageList>
+          class="group flex items-center gap-3 p-3 transition-colors hover:bg-elevated/50"
+        >
+          <span class="inline-flex items-center justify-center size-8 shrink-0 rounded-full bg-elevated text-muted">
+            <UIcon :name="doc.icon" class="size-4" />
+          </span>
+          <span class="min-w-0 flex-1">
+            <span class="block text-sm font-medium text-highlighted">{{ doc.title }}</span>
+            <span class="block text-xs text-muted mt-0.5">{{ doc.description }}</span>
+          </span>
+          <UIcon
+            name="i-lucide-arrow-right"
+            class="size-4 shrink-0 text-dimmed transition-transform group-hover:translate-x-0.5 group-hover:text-muted"
+          />
+        </NuxtLink>
+      </div>
     </div>
   </div>
 </template>

From 18baae73de4d11a8fbfc323bf47f70dd4fc024e8 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 27 Aug 2026 04:53:40 +0000
Subject: [PATCH 6/7] docs: color only the selected card, drop the check mark,
 add question icons

- Apply each item's accent color to the card's border/background/ring and its
  icon badge only when selected; unselected cards stay neutral gray.
- Remove the corner check mark (color now signals selection).
- Add a leading icon to every question heading.
---
 .../global/GettingStartedWizard.vue           | 60 ++++++++++---------
 1 file changed, 32 insertions(+), 28 deletions(-)

diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
index befb7a54..679fc7e3 100644
--- a/docs/app/components/global/GettingStartedWizard.vue
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -14,36 +14,39 @@ interface WizardItem {
   value: string
   label: string
   icon: string
-  /** Accent color key from `ICON_COLORS`, giving each item its own tinted badge. */
-  color: keyof typeof ICON_COLORS
+  /** Accent color key from `ITEM_COLORS`, applied once the item is selected. */
+  color: keyof typeof ITEM_COLORS
   description?: string
 }
 
 /**
- * Per-item icon badge colors. Spelled out as full class strings (not
- * interpolated) so Tailwind's scanner keeps them in the build.
+ * Per-item accent colors, applied only to a *selected* card (its badge, plus
+ * the card's border/background/ring); unselected cards stay neutral gray.
+ * Spelled out as full class strings (not interpolated) so Tailwind's scanner
+ * keeps them in the build.
  */
-const ICON_COLORS = {
-  sky: 'bg-sky-500/10 text-sky-500',
-  indigo: 'bg-indigo-500/10 text-indigo-500',
-  violet: 'bg-violet-500/10 text-violet-500',
-  purple: 'bg-purple-500/10 text-purple-500',
-  fuchsia: 'bg-fuchsia-500/10 text-fuchsia-500',
-  pink: 'bg-pink-500/10 text-pink-500',
-  rose: 'bg-rose-500/10 text-rose-500',
-  amber: 'bg-amber-500/10 text-amber-500',
-  orange: 'bg-orange-500/10 text-orange-500',
-  emerald: 'bg-emerald-500/10 text-emerald-500',
-  teal: 'bg-teal-500/10 text-teal-500',
-  cyan: 'bg-cyan-500/10 text-cyan-500',
-  blue: 'bg-blue-500/10 text-blue-500',
-  green: 'bg-green-500/10 text-green-500',
+const ITEM_COLORS = {
+  sky: { badge: 'bg-sky-500/10 text-sky-500', card: 'border-sky-500/60 bg-sky-500/5 ring-1 ring-sky-500/20' },
+  indigo: { badge: 'bg-indigo-500/10 text-indigo-500', card: 'border-indigo-500/60 bg-indigo-500/5 ring-1 ring-indigo-500/20' },
+  violet: { badge: 'bg-violet-500/10 text-violet-500', card: 'border-violet-500/60 bg-violet-500/5 ring-1 ring-violet-500/20' },
+  purple: { badge: 'bg-purple-500/10 text-purple-500', card: 'border-purple-500/60 bg-purple-500/5 ring-1 ring-purple-500/20' },
+  fuchsia: { badge: 'bg-fuchsia-500/10 text-fuchsia-500', card: 'border-fuchsia-500/60 bg-fuchsia-500/5 ring-1 ring-fuchsia-500/20' },
+  pink: { badge: 'bg-pink-500/10 text-pink-500', card: 'border-pink-500/60 bg-pink-500/5 ring-1 ring-pink-500/20' },
+  rose: { badge: 'bg-rose-500/10 text-rose-500', card: 'border-rose-500/60 bg-rose-500/5 ring-1 ring-rose-500/20' },
+  amber: { badge: 'bg-amber-500/10 text-amber-500', card: 'border-amber-500/60 bg-amber-500/5 ring-1 ring-amber-500/20' },
+  orange: { badge: 'bg-orange-500/10 text-orange-500', card: 'border-orange-500/60 bg-orange-500/5 ring-1 ring-orange-500/20' },
+  emerald: { badge: 'bg-emerald-500/10 text-emerald-500', card: 'border-emerald-500/60 bg-emerald-500/5 ring-1 ring-emerald-500/20' },
+  teal: { badge: 'bg-teal-500/10 text-teal-500', card: 'border-teal-500/60 bg-teal-500/5 ring-1 ring-teal-500/20' },
+  cyan: { badge: 'bg-cyan-500/10 text-cyan-500', card: 'border-cyan-500/60 bg-cyan-500/5 ring-1 ring-cyan-500/20' },
+  blue: { badge: 'bg-blue-500/10 text-blue-500', card: 'border-blue-500/60 bg-blue-500/5 ring-1 ring-blue-500/20' },
+  green: { badge: 'bg-green-500/10 text-green-500', card: 'border-green-500/60 bg-green-500/5 ring-1 ring-green-500/20' },
 } as const
 
 interface WizardSection {
   key: string
   title: string
   hint: string
+  icon: string
   items: WizardItem[]
 }
 
@@ -60,6 +63,7 @@ const sections: WizardSection[] = [
     key: 'environments',
     title: 'Target environments',
     hint: 'What do you expect your tool to work with?',
+    icon: 'i-lucide-target',
     items: [
       { value: 'standalone', label: 'Standalone', icon: 'i-lucide-terminal', color: 'sky', description: 'A CLI or dev server with no host framework' },
       { value: 'framework', label: 'Specific framework', icon: 'i-lucide-shapes', color: 'violet', description: 'Specifically for frameworks like Vite, Next.js, Nuxt, etc.' },
@@ -70,6 +74,7 @@ const sections: WizardSection[] = [
     key: 'dataSource',
     title: 'Data source',
     hint: 'Where do you want to visualize data from?',
+    icon: 'i-lucide-database',
     items: [
       { value: 'node', label: 'The node side', icon: 'i-lucide-server', color: 'indigo', description: 'Server state, build output, the filesystem, child processes' },
       { value: 'browser', label: 'The user\'s web app', icon: 'i-lucide-app-window', color: 'cyan', description: 'State living in the page you\'re developing' },
@@ -79,6 +84,7 @@ const sections: WizardSection[] = [
     key: 'availability',
     title: 'Data availability',
     hint: 'When is the data available?',
+    icon: 'i-lucide-clock',
     items: [
       { value: 'dev', label: 'Development time', icon: 'i-lucide-code', color: 'blue', description: 'Live, over a running dev server' },
       { value: 'build', label: 'Production build time', icon: 'i-lucide-hammer', color: 'amber', description: 'Data from the production build' },
@@ -90,6 +96,7 @@ const sections: WizardSection[] = [
     key: 'frontend',
     title: 'Frontend approach',
     hint: 'How do you want to build the frontend view?',
+    icon: 'i-lucide-palette',
     items: [
       { value: 'framework', label: 'A preferred framework', icon: 'i-lucide-component', color: 'green', description: 'Vue, React, Svelte, Solid...' },
       { value: 'webcomponents', label: 'Web Components', icon: 'i-lucide-box', color: 'orange', description: 'Use Web Components for renderering' },
@@ -100,6 +107,7 @@ const sections: WizardSection[] = [
     key: 'requirements',
     title: 'Other requirements',
     hint: 'Any specific requirements?',
+    icon: 'i-lucide-list-checks',
     items: [
       { value: 'agent', label: 'Exposed to coding agents', icon: 'i-lucide-bot', color: 'pink', description: 'Some functionality should be available to coding agents.' },
       { value: 'terminal', label: 'Sub process access', icon: 'i-lucide-square-terminal', color: 'amber', description: 'Need to spawn other child process from the node side' },
@@ -270,7 +278,8 @@ function reset(): void {
       class="px-5 py-4 sm:px-6"
     >
       <div class="flex flex-wrap items-baseline gap-x-2 mb-3">
-        <p class="font-medium text-highlighted">
+        <p class="flex items-center gap-2 font-medium text-highlighted">
+          <UIcon :name="section.icon" class="size-4 text-muted" />
           {{ section.hint }}
         </p>
         <p class="text-xs text-muted uppercase tracking-widest">
@@ -287,13 +296,13 @@ function reset(): void {
           :aria-checked="isChecked(section.key, item.value)"
           class="relative flex items-center gap-3 rounded-lg border p-3 text-left transition-colors cursor-pointer"
           :class="isChecked(section.key, item.value)
-            ? 'border-primary/80 bg-primary/10 ring-1 ring-primary/20'
+            ? ITEM_COLORS[item.color].card
             : 'border-default hover:border-accented hover:bg-elevated/50'"
           @click="toggle(section.key, item.value)"
         >
           <span
-            class="inline-flex items-center justify-center size-8 shrink-0 rounded-full"
-            :class="ICON_COLORS[item.color]"
+            class="inline-flex items-center justify-center size-8 shrink-0 rounded-full transition-colors"
+            :class="isChecked(section.key, item.value) ? ITEM_COLORS[item.color].badge : 'bg-elevated text-muted'"
           >
             <UIcon :name="item.icon" class="size-4" />
           </span>
@@ -304,11 +313,6 @@ function reset(): void {
               class="block text-xs text-muted mt-0.5"
             >{{ item.description }}</span>
           </span>
-          <UIcon
-            v-if="isChecked(section.key, item.value)"
-            name="i-lucide-circle-check"
-            class="size-4 shrink-0 text-primary"
-          />
         </button>
       </div>
     </div>

From 0fa1d4e97f0413d0132386218711a0721ea6666f Mon Sep 17 00:00:00 2001
From: Anthony Fu <github@antfu.me>
Date: Thu, 27 Aug 2026 14:48:30 +0900
Subject: [PATCH 7/7] chore: update

---
 docs/app/app.config.ts                              | 1 +
 docs/app/components/global/GettingStartedWizard.vue | 5 +----
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/app/app.config.ts b/docs/app/app.config.ts
index f42ff721..6a12306d 100644
--- a/docs/app/app.config.ts
+++ b/docs/app/app.config.ts
@@ -98,6 +98,7 @@ export default defineAppConfig({
             '/adapters',
             '/guide/standalone-cli',
             '/guide/client',
+            '/guide/in-page-channel',
             '/guide/transports',
             '/guide/security',
           ],
diff --git a/docs/app/components/global/GettingStartedWizard.vue b/docs/app/components/global/GettingStartedWizard.vue
index 679fc7e3..4e2ddd94 100644
--- a/docs/app/components/global/GettingStartedWizard.vue
+++ b/docs/app/components/global/GettingStartedWizard.vue
@@ -166,7 +166,7 @@ const RECOMMENDATIONS: Record<string, string[]> = {
   'dataSource:browser': ['/guide/client-context', '/guide/deep-linking', '/plugins/a11y'],
 
   'environments:standalone': ['/guide/standalone-cli', '/adapters/cac', '/adapters/build'],
-  'environments:framework': ['/frameworks/vite', '/frameworks/next', '/frameworks/nuxt', '/adapters/vite', '/adapters/embedded'],
+  'environments:framework': ['/adapters'],
   'environments:all': ['/adapters/initiate', '/adapters', '/guide/devframe-definition'],
 
   'availability:dev': ['/guide/rpc', '/guide/transports'],
@@ -282,9 +282,6 @@ function reset(): void {
           <UIcon :name="section.icon" class="size-4 text-muted" />
           {{ section.hint }}
         </p>
-        <p class="text-xs text-muted uppercase tracking-widest">
-          {{ section.title }}
-        </p>
       </div>
 
       <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-2.5">