docs: brand theme color, version nav with migrations, richer landing, vercel build

Author: antfubot

docs/app/app.config.ts

@@ -1,3 +1,5 @@
+import devframePkg from '../../packages/devframe/package.json'
+
 export default defineAppConfig({
   seo: {
     siteName: 'Devframe',
@@ -21,6 +23,20 @@ export default defineAppConfig({
       },
       { label: 'Plugins', sections: ['plugins'], link: 'section' as const },
       { label: 'Errors', sections: ['errors'], link: 'section' as const },
+      {
+        label: `v${devframePkg.version}`,
+        to: '/migrations',
+        activePath: '/migrations',
+        children: [
+          { label: 'Migrations overview', to: '/migrations' },
+          { label: 'Migrating to 0.9', to: '/migrations/migration-0.9' },
+          { label: 'Migrating to 0.8', to: '/migrations/migration-0.8' },
+          { label: 'Migrating to 0.7', to: '/migrations/migration-0.7' },
+          { label: 'Migrating to 0.6', to: '/migrations/migration-0.6' },
+          { label: 'Release notes', to: 'https://github.com/devframes/devframe/releases' },
+          { label: 'Contributing', to: 'https://github.com/devframes/devframe/blob/main/CONTRIBUTING.md' },
+        ],
+      },
     ],
   },
 
@@ -99,15 +115,6 @@ export default defineAppConfig({
           ],
         },
         { title: 'Ecosystem', items: ['/guide/built-with'] },
-        {
-          title: 'Migrations',
-          items: [
-            '/guide/migration-0.9',
-            '/guide/migration-0.8',
-            '/guide/migration-0.7',
-            '/guide/migration-0.6',
-          ],
-        },
       ],
     },
     ogImage: {
@@ -130,7 +137,7 @@ export default defineAppConfig({
 
   ui: {
     colors: {
-      primary: 'green',
+      primary: 'sage',
       neutral: 'neutral',
     },
   },

docs/app/assets/css/devframe.css

@@ -0,0 +1,19 @@
+/*
+ * Devframe brand palette (sage green, anchored on the old VitePress brand
+ * color #517158). Nuxt UI maps `--ui-color-primary-*` to `var(--color-sage-*)`
+ * when `ui.colors.primary` is `sage`, so defining these custom properties is
+ * enough to theme every primary accent (links, section labels, syntax hints).
+ */
+:root {
+  --color-sage-50: #f3f7f3;
+  --color-sage-100: #e3ede4;
+  --color-sage-200: #c8dcca;
+  --color-sage-300: #9fc0a4;
+  --color-sage-400: #6f9d77;
+  --color-sage-500: #517158;
+  --color-sage-600: #445f4a;
+  --color-sage-700: #384d3d;
+  --color-sage-800: #2f3f33;
+  --color-sage-900: #28352b;
+  --color-sage-950: #131d16;
+}

docs/app/composables/useFilteredNavigation.ts

@@ -55,7 +55,16 @@ export function useFilteredNavigation(): ComputedRef<NavItem[]> {
       ? headerGroups
       : nav.map(item => ({ label: item.title, sections: [segmentOf(item.path, base)] }))
 
-    const active = groups.find(group => group.sections?.includes(seg)) ?? groups[0]
+    const matched = groups.find(group => group.sections?.includes(seg))
+    // A section reachable only through a manual tab (e.g. migrations, under the
+    // version dropdown) still gets its own flat sidebar.
+    if (!matched) {
+      const node = nav.find(item => segmentOf(item.path, base) === seg)
+      if (node)
+        return (node.children ?? []).filter(child => child.path !== node.path)
+    }
+
+    const active = matched ?? groups[0]
     const sections = active?.sections
     // Manual tabs (no sections) have no content sidebar; fall back to the full tree.
     if (!sections?.length)

docs/content/7.migrations/.navigation.yml

@@ -0,0 +1 @@
+title: Migrations

docs/content/1.guide/24.migration-0.9.md …/content/7.migrations/1.migration-0.9.mddocs/content/1.guide/24.migration-0.9.md renamed to docs/content/7.migrations/1.migration-0.9.md docs/content/1.guide/24.migration-0.9.md renamed to docs/content/7.migrations/1.migration-0.9.md

@@ -0,0 +1,15 @@
+---
+title: 'Migrations'
+description: 'Version-by-version upgrade guides for devframe and @devframes/hub. Each release below has a drop-in path from the previous one.'
+---
+
+Upgrade guides for devframe and `@devframes/hub`, newest first. Each one lists every breaking change with its drop-in replacement.
+
+| Version | What changed |
+| ------- | ------------ |
+| [Migrating to 0.9](/migrations/migration-0.9) | Removes the compatibility shims deprecated across the 0.7 series and trims the public API. |
+| [Migrating to 0.8](/migrations/migration-0.8) | Makes RPC schemas validator-neutral and runtime-validated, and adds the agent-native MCP surface. |
+| [Migrating to 0.7](/migrations/migration-0.7) | Makes `cac` an optional peer and moves json-render into an opt-in package. |
+| [Migrating to 0.6](/migrations/migration-0.6) | Tightens `defineDevframe`'s metadata, replaces the terminal and WebSocket transports, and adds enforced auth. |
+
+For the full changelog of every release, see the [release notes on GitHub](https://github.com/devframes/devframe/releases).

docs/content/1.guide/25.migration-0.8.md …/content/7.migrations/2.migration-0.8.mddocs/content/1.guide/25.migration-0.8.md renamed to docs/content/7.migrations/2.migration-0.8.md docs/content/1.guide/25.migration-0.8.md renamed to docs/content/7.migrations/2.migration-0.8.md

@@ -41,16 +41,6 @@ A framework-neutral foundation for devtools. One definition becomes a Web Standa
   Get started
   :::
 
-  :::u-button
-  ---
-  to: /guide#why-it-exists
-  color: neutral
-  variant: subtle
-  size: lg
-  ---
-  Why Devframe
-  :::
-
   :::u-button
   ---
   icon: i-simple-icons-github
@@ -64,6 +54,17 @@ A framework-neutral foundation for devtools. One definition becomes a Web Standa
   :::
 ::
 
+::u-page-section
+  :::callout
+  ---
+  icon: i-lucide-newspaper
+  to: https://antfu.me/posts/pluggable-extensible-playful-devtools
+  target: _blank
+  ---
+  Read the announcement — **Pluggable, Extensible, and Playful DevTools** — for the vision behind devframe.
+  :::
+::
+
 ::landing-features
 #headline
 Foundation
@@ -124,18 +125,233 @@ One definition, every entry point
   :::
 ::
 
+::landing-tabs
+---
+items:
+  - icon: i-simple-icons-hono
+    title: Hono
+    description: Pass the Web Standard request straight to the handler.
+  - icon: i-lucide-server
+    title: Nitro
+    description: Mount the same handler on a catch-all event route.
+  - icon: i-simple-icons-nextdotjs
+    title: Next.js
+    description: Wire the handler into an App Router route handler.
+  - icon: i-simple-icons-vite
+    title: Vite
+    description: Use the connect-style middleware the same instance provides.
+---
+
+#headline
+Portability
+
+#title
+The same handler, mounted natively
+
+#description
+A devframe's boundary is simply the Web Standard `Request` and `Response`. Any framework that speaks that — or connect-style middleware — mounts the same tool and inherits the whole ecosystem. Only the host-facing glue changes. [See all adapters](/adapters/initiate).
+
+#code-0
+  ```ts [server.ts]
+  import { Hono } from 'hono'
+  import { devtools } from './devtools'
+
+  const app = new Hono()
+
+  app.all(`${devtools.base}*`, c => devtools.handler(c.req.raw))
+  ```
+
+#code-1
+  ```ts [routes/[...devtools].ts]
+  import { devtools } from '../devtools'
+
+  export default defineEventHandler(event => devtools.handler(toWebRequest(event)))
+  ```
+
+#code-2
+  ```ts [app/__my-tool/[...all]/route.ts]
+  import { devtools } from '@/devtools'
+
+  export const GET = (req: Request) => devtools.handler(req)
+  export const POST = GET
+  ```
+
+#code-3
+  ```ts [vite.config.ts]
+  import { devtools } from './devtools'
+
+  export default defineConfig({
+    plugins: [{
+      name: 'my-tool',
+      configureServer: server => server.middlewares.use(devtools.nodeMiddleware),
+    }],
+  })
+  ```
+::
+
+::landing-tabs
+---
+reverse: true
+items:
+  - icon: i-lucide-terminal
+    title: CLI
+    description: Ship a standalone command any project can run.
+  - icon: i-lucide-server-cog
+    title: Dev server
+    description: A dedicated dev server for local iteration.
+  - icon: i-lucide-bot
+    title: MCP
+    description: Expose the tool to coding agents over MCP.
+  - icon: i-lucide-package
+    title: Static report
+    description: Build a self-contained SPA snapshot for CI.
+---
+
+#headline
+Adapters
+
+#title
+Package it the way your tool ships
+
+#description
+The handler is the smallest common denominator. Higher-level adapters package that same definition into familiar forms — pick the entry points your package needs. [Browse the adapters](/adapters).
+
+#code-0
+  ```ts [cli.ts]
+  import { createCac } from 'devframe/adapters/cac'
+  import myDevframe from './my-tool'
+
+  createCac(myDevframe).parse()
+  ```
+
+#code-1
+  ```ts [dev.ts]
+  import { createDevServer } from 'devframe/adapters/dev'
+  import myDevframe from './my-tool'
+
+  createDevServer(myDevframe)
+  ```
+
+#code-2
+  ```ts [mcp.ts]
+  import { createMcpServer } from 'devframe/adapters/mcp'
+  import myDevframe from './my-tool'
+
+  createMcpServer(myDevframe, { transport: 'stdio' })
+  ```
+
+#code-3
+  ```ts [report.ts]
+  import { createBuild } from 'devframe/adapters/build'
+  import myDevframe from './my-tool'
+
+  createBuild(myDevframe, { outDir: 'dist-static' })
+  ```
+::
+
+::landing-tabs
+---
+items:
+  - icon: i-lucide-eye
+    title: Visual
+    description: Explore, overview, and compare through a web UI.
+  - icon: i-lucide-bot
+    title: Agentic
+    description: Retrieve focused context and carry out multi-step actions.
+---
+
+#headline
+Interfaces
+
+#title
+One capability, two interfaces
+
+#description
+RPC functions stay private by default and opt into agent exposure explicitly. The [MCP adapter](/adapters/mcp) translates those functions, resources, and selected shared state into an agent-consumable surface — the presentation changes, the source of truth stays the same.
+
+#code-0
+  ```ts [rpc.ts]
+  import { defineRpcFunction } from 'devframe'
+
+  export const inspectBuild = defineRpcFunction({
+    name: 'inspect-build',
+    type: 'query',
+    handler: () => readBuildGraph(),
+  })
+  ```
+
+#code-1
+  ```ts [rpc.ts]
+  export const inspectBuild = defineRpcFunction({
+    name: 'inspect-build',
+    type: 'query',
+    // opt this capability into the agent surface
+    agent: { description: 'Read the current build graph and chunk sizes.' },
+    handler: () => readBuildGraph(),
+  })
+  ```
+::
+
+::landing-tabs
+---
+reverse: true
+items:
+  - icon: i-lucide-layout-dashboard
+    title: Compose
+    description: Register many devframes as plugins of one hub.
+  - icon: i-lucide-plug
+    title: Mount
+    description: Serve the whole collection behind one handler.
+---
+
+#headline
+Hub
+
+#title
+From one devframe to a devtools host
+
+#description
+When several devtools run at once, discovery becomes the problem. `@devframes/hub` is a headless composition layer: many devframes register docks, commands, terminals, and shared state, and appear through one consistent entry. [Learn about the hub](/guide/hub).
+
+#code-0
+  ```ts [hub.ts]
+  import { initHub } from '@devframes/hub/initiate'
+  import { createTerminalsDevframe } from '@devframes/plugin-terminals'
+
+  const hub = initHub({
+    base: '/__devframes/',
+    devframes: [
+      createTerminalsDevframe(),
+      // ...more devframes
+    ],
+    ui: await import('@devframes/hub-ui').then(m => m.createUi()),
+  })
+  ```
+
+#code-1
+  ```ts [server.ts]
+  import { Hono } from 'hono'
+  import { hub } from './hub'
+
+  // the same handler/middleware API as a standalone devframe
+  new Hono().all(`${hub.base}*`, c => hub.handler(c.req.raw))
+  ```
+::
+
 ::landing-cta
 ---
 links:
   - label: Get started
     to: /guide
     trailingIcon: i-lucide-arrow-right
     size: lg
-  - label: Browse the plugins
-    to: /plugins
+  - label: Read the announcement
+    to: https://antfu.me/posts/pluggable-extensible-playful-devtools
+    target: _blank
     color: neutral
     variant: subtle
     size: lg
+    icon: i-lucide-newspaper
 ---
 #title
 Ship your devtool everywhere