docus 5.8.0 → 5.9.0

package/README.md

@@ -1,4 +1,4 @@
-[![docus](https://docus.dev/__og-image__/static/og.png)](https://docus.dev)
+[![docus](https://docus.dev/_og/s/c_Landing,title_Write+beautiful+docs+with+Markdown,description_Ship+fast+flexible+and+SEO-optimized+documentation+with+beautiful+design+out+of+the+box.+Docus+brings+together+the+best+of+the+Nuxt+ecosystem.+Powered+by+Nuxt+UI.,p_Ii9lbiI.png)](https://docus.dev)
 
 # Docus
 

package/app/app.config.ts

@@ -1,6 +1,7 @@
 export default defineAppConfig({
   docus: {
     locale: 'en',
+    colorMode: '',
   },
   ui: {
     colors: {

package/app/app.vue

@@ -2,9 +2,12 @@
 import type { ContentNavigationItem, PageCollections } from '@nuxt/content'
 import * as nuxtUiLocales from '@nuxt/ui/locale'
 import { transformNavigation } from './utils/navigation'
+import { useDocusColorMode } from './composables/useDocusColorMode'
 import { useSubNavigation } from './composables/useSubNavigation'
 
-const { seo } = useAppConfig()
+const appConfig = useAppConfig()
+const { seo } = appConfig
+const { forced: forcedColorMode } = useDocusColorMode()
 const site = useSiteConfig()
 const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n()
 const { isEnabled: isAssistantEnabled, panelWidth: assistantPanelWidth, shouldPushContent } = useAssistant()
@@ -79,6 +82,7 @@ const { subNavigationMode } = useSubNavigation(navigation)
       <LazyUContentSearch
         :files="files"
         :navigation="navigation"
+        :color-mode="!forcedColorMode"
       />
       <template v-if="isAssistantEnabled">
         <LazyAssistantPanel />

package/app/components/OgImage/Docs.takumi.vue

@@ -0,0 +1,43 @@
+<script lang="ts" setup>
+const { title, description, headline } = defineProps<{ title?: string, description?: string, headline?: string }>()
+
+const appConfig = useAppConfig()
+const { name: siteName } = useSiteConfig()
+const primaryColor = appConfig.ui?.colors?.primary ?? 'emerald'
+</script>
+
+<template>
+  <div class="w-full h-full flex flex-col justify-between bg-neutral-950 px-[80px] py-[60px]">
+    <!-- Radial glow top-right: wide soft layer -->
+    <div class="absolute top-0 right-0 w-[700px] h-[700px] bg-[radial-gradient(circle_at_top_right,rgba(255,255,255,0.10)_0%,rgba(255,255,255,0.04)_40%,transparent_70%)]" />
+    <!-- Radial glow top-right: tight bright core -->
+    <div class="absolute top-0 right-0 w-[350px] h-[350px] bg-[radial-gradient(circle_at_top_right,rgba(255,255,255,0.22)_0%,rgba(255,255,255,0.08)_35%,transparent_65%)]" />
+
+    <div class="flex-1 flex flex-col justify-center">
+      <p
+        v-if="headline"
+        :class="`uppercase text-[22px] font-bold m-0 mb-5 tracking-[0.05em] text-${primaryColor}-500`"
+      >
+        {{ headline }}
+      </p>
+      <h1
+        v-if="title"
+        class="m-0 mb-6 text-[50px] font-bold text-white leading-[1.1] w-full max-w-[900px] wrap-break-word"
+      >
+        {{ title?.slice(0, 60) }}
+      </h1>
+      <p
+        v-if="description"
+        class="m-0 text-[28px] text-neutral-400 leading-[1.4] w-full max-w-[900px] wrap-break-word"
+      >
+        {{ description?.slice(0, 200) }}
+      </p>
+    </div>
+
+    <div class="flex">
+      <div class="text-white text-[18px] font-normal rounded-lg px-5 py-2">
+        {{ siteName }}
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/OgImage/Landing.takumi.vue

@@ -0,0 +1,67 @@
+<script lang="ts" setup>
+const { title, description } = defineProps<{ title?: string, description?: string }>()
+
+const appConfig = useAppConfig()
+const { name: siteName } = useSiteConfig()
+const primaryColor = appConfig.ui?.colors?.primary ?? 'emerald'
+const logoPath = appConfig.header?.logo?.dark || appConfig.header?.logo?.light
+
+const logoSvg = await fetchLogoSvg(logoPath)
+
+async function fetchLogoSvg(path?: string): Promise<string> {
+  if (!path) return ''
+  try {
+    const { url: siteUrl } = useSiteConfig()
+    const url = path.startsWith('http') ? path : `${siteUrl}${path}`
+    const svg = await $fetch<string>(url, { responseType: 'text' })
+    return svg.replace('<svg', '<svg width="48" height="48"')
+  }
+  catch {
+    return ''
+  }
+}
+</script>
+
+<template>
+  <div class="w-full h-full flex flex-col justify-between bg-neutral-950 px-[80px] py-[60px]">
+    <!-- Radial glow top-right: wide soft layer -->
+    <div class="absolute top-0 right-0 w-[700px] h-[700px] bg-[radial-gradient(circle_at_top_right,rgba(255,255,255,0.10)_0%,rgba(255,255,255,0.04)_40%,transparent_70%)]" />
+    <!-- Radial glow top-right: tight bright core -->
+    <div class="absolute top-0 right-0 w-[350px] h-[350px] bg-[radial-gradient(circle_at_top_right,rgba(255,255,255,0.22)_0%,rgba(255,255,255,0.08)_35%,transparent_65%)]" />
+
+    <div class="flex-1 flex flex-col justify-center w-full">
+      <div
+        v-if="logoSvg"
+        class="flex justify-center mb-8"
+      >
+        <!-- eslint-disable-next-line vue/no-v-html -->
+        <div
+          class="w-[48px] h-[48px]"
+          v-html="logoSvg"
+        />
+      </div>
+      <div
+        v-if="title"
+        class="flex justify-center mb-6"
+      >
+        <h1 class="m-0 text-[50px] font-bold text-white leading-[1.1] text-center wrap-break-word">
+          {{ title?.slice(0, 60) }}
+        </h1>
+      </div>
+      <div
+        v-if="description"
+        class="flex justify-center"
+      >
+        <p class="m-0 text-[28px] text-neutral-400 leading-[1.4] text-center wrap-break-word">
+          {{ description?.slice(0, 200) }}
+        </p>
+      </div>
+    </div>
+
+    <div class="flex">
+      <div :class="`text-[18px] font-normal rounded-lg px-5 py-2 text-${primaryColor}-500`">
+        {{ siteName }}
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/app/AppFooterRight.vue

@@ -1,5 +1,8 @@
 <script setup lang="ts">
+import { useDocusColorMode } from '../../composables/useDocusColorMode'
+
 const appConfig = useAppConfig()
+const { forced: forcedColorMode } = useDocusColorMode()
 
 interface FooterLink {
   'icon': string
@@ -44,5 +47,5 @@ const links = computed<FooterLink[]>(() => {
       v-bind="{ color: 'neutral', variant: 'ghost', ...link }"
     />
   </template>
-  <UColorModeButton />
+  <UColorModeButton v-if="!forcedColorMode" />
 </template>

package/app/components/app/AppHeader.vue

@@ -1,8 +1,10 @@
 <script setup lang="ts">
+import { useDocusColorMode } from '../../composables/useDocusColorMode'
 import { useDocusI18n } from '../../composables/useDocusI18n'
-import { useSubNavigation } from '~/composables/useSubNavigation'
+import { useSubNavigation } from '../../composables/useSubNavigation'
 
 const appConfig = useAppConfig()
+const { forced: forcedColorMode } = useDocusColorMode()
 const site = useSiteConfig()
 
 const { isEnabled: isAssistantEnabled } = useAssistant()
@@ -58,7 +60,7 @@ const links = computed(() => appConfig.github && appConfig.github.url
 
       <UContentSearchButton class="lg:hidden" />
 
-      <ClientOnly>
+      <ClientOnly v-if="!forcedColorMode">
         <UColorModeButton />
 
         <template #fallback>

package/app/components/app/AppHeaderBottom.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { useSubNavigation } from '~/composables/useSubNavigation'
+import { useSubNavigation } from '../../composables/useSubNavigation'
 
 const { sections } = useSubNavigation()
 </script>

package/app/components/docs/DocsAsideLeftTop.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { useSubNavigation } from '~/composables/useSubNavigation'
+import { useSubNavigation } from '../../composables/useSubNavigation'
 
 const { subNavigationMode, sections } = useSubNavigation()
 </script>

package/app/components/docs/DocsAsideMobileBar.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { useSubNavigation } from '~/composables/useSubNavigation'
+import { useSubNavigation } from '../../composables/useSubNavigation'
 import type { ContentTocLink } from '@nuxt/ui'
 
 defineProps<{

package/app/components/docs/DocsAsideRight.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { useSubNavigation } from '~/composables/useSubNavigation'
+import { useSubNavigation } from '../../composables/useSubNavigation'
 import type { DocsCollectionItem } from '@nuxt/content'
 
 const props = defineProps<{

package/app/composables/useDocusColorMode.ts

@@ -0,0 +1,7 @@
+export function useDocusColorMode() {
+  const appConfig = useAppConfig()
+  const forced = (appConfig.docus as { colorMode?: string })?.colorMode
+  return {
+    forced: forced === 'light' || forced === 'dark' ? forced : undefined,
+  }
+}

package/app/error.vue

@@ -3,11 +3,13 @@ import type { NuxtError } from '#app'
 import type { ContentNavigationItem, PageCollections } from '@nuxt/content'
 import * as nuxtUiLocales from '@nuxt/ui/locale'
 import { transformNavigation } from './utils/navigation'
+import { useDocusColorMode } from './composables/useDocusColorMode'
 
 const props = defineProps<{
   error: NuxtError
 }>()
 
+const { forced: forcedColorMode } = useDocusColorMode()
 const { locale, locales, isEnabled, t, switchLocalePath } = useDocusI18n()
 
 const nuxtUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales] || nuxtUiLocales.en)
@@ -70,6 +72,7 @@ provide('navigation', navigation)
       <LazyUContentSearch
         :files="files"
         :navigation="navigation"
+        :color-mode="!forcedColorMode"
       />
     </ClientOnly>
   </UApp>

package/app/middleware/colorMode.global.ts

@@ -0,0 +1,8 @@
+import { useDocusColorMode } from '../composables/useDocusColorMode'
+
+export default defineNuxtRouteMiddleware((to) => {
+  const { forced } = useDocusColorMode()
+  if (forced) {
+    to.meta.colorMode = forced
+  }
+})

package/app/pages/[[lang]]/[...slug].vue

@@ -45,8 +45,10 @@ watch(() => navigation?.value, () => {
   headline.value = findPageHeadline(navigation?.value, page.value?.path) || headline.value
 })
 
-defineOgImageComponent('Docs', {
+defineOgImage('Docs', {
   headline: headline.value,
+  title: title?.slice(0, 60),
+  description: formatOgDescription(title, description),
 })
 
 const github = computed(() => appConfig.github ? appConfig.github : null)
@@ -115,17 +117,19 @@ addPrerenderPath(`/raw${route.path}.md`)
           >
             {{ t('docs.edit') }}
           </UButton>
-          <span>{{ t('common.or') }}</span>
-          <UButton
-            variant="link"
-            color="neutral"
-            :to="`${github.url}/issues/new/choose`"
-            target="_blank"
-            icon="i-lucide-alert-circle"
-            :ui="{ leadingIcon: 'size-4' }"
-          >
-            {{ t('docs.report') }}
-          </UButton>
+          <template v-if="github?.url">
+            <span>{{ t('common.or') }}</span>
+            <UButton
+              variant="link"
+              color="neutral"
+              :to="`${github.url}/issues/new/choose`"
+              target="_blank"
+              icon="i-lucide-alert-circle"
+              :ui="{ leadingIcon: 'size-4' }"
+            >
+              {{ t('docs.report') }}
+            </UButton>
+          </template>
         </div>
       </USeparator>
       <UContentSurround :surround="surround" />

package/app/templates/landing.vue

@@ -23,9 +23,9 @@ useSeo({
 })
 
 if (!page.value?.seo?.ogImage) {
-  defineOgImageComponent('Landing', {
-    title,
-    description,
+  defineOgImage('Landing', {
+    title: title?.slice(0, 60),
+    description: formatOgDescription(title, description),
   })
 }
 </script>

package/app/utils/ogImage.ts

@@ -0,0 +1,23 @@
+// nuxt-og-image caps the encoded URL segment at 200 chars.
+// Fixed overhead (component name, param keys, path encoding) is ~50 chars,
+// leaving a ~150-char budget for title + description combined.
+const OG_BUDGET = 150
+
+/**
+ * Trims description to fit within the nuxt-og-image 200-char URL segment limit,
+ * accounting for the title length and trying to cut at the last sentence boundary.
+ */
+export function formatOgDescription(title: string | undefined, description: string | undefined): string | undefined {
+  if (!description) return undefined
+
+  const titleLen = Math.min(title?.length ?? 0, 60)
+  const maxLen = OG_BUDGET - titleLen
+  if (maxLen <= 0) return undefined
+
+  const cleaned = description.replace(/,/g, '')
+  if (cleaned.length <= maxLen) return cleaned
+
+  const truncated = cleaned.slice(0, maxLen)
+  const lastDot = truncated.lastIndexOf('.')
+  return lastDot > 0 ? truncated.slice(0, lastDot + 1) : truncated
+}

package/modules/assistant/README.md

@@ -35,13 +35,20 @@ export default defineNuxtConfig({
 })
 ```
 
-4. Set up your API key as an environment variable:
+4. Authenticate to AI Gateway in one of two ways:
+
+   - **`AI_GATEWAY_API_KEY`** — Set it in the Vercel project env UI (and locally in `.env` if you want).
+   - **OIDC** — On Vercel, `VERCEL_OIDC_TOKEN` is injected automatically; you do **not** add it (or an API key) in the dashboard. For local builds, run `vercel env pull` on a linked project so `.env` contains the token:
 
 ```bash
+# Option A — API key (dashboard + optional local .env)
 AI_GATEWAY_API_KEY=your-gateway-key
+
+# Option B — local only, after vercel env pull (not set manually on Vercel)
+VERCEL_OIDC_TOKEN=...
 ```
 
-> **Note:** The module will only be enabled if `AI_GATEWAY_API_KEY` is detected. If no key is found, the module is disabled and a message is logged to the console.
+> **Note:** The module enables when `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` is present at build time. On Vercel, OIDC covers that without you creating env vars in the UI. If neither is available at build, the module stays disabled and a warning is logged.
 
 ## Usage
 
@@ -199,7 +206,7 @@ Composable for syntax highlighting code blocks with Shiki.
 - Nuxt 4.x
 - Nuxt UI 3.x (for `USlideover`, `UButton`, `UTextarea`, `UChatMessages`, etc.)
 - An MCP server running (path configurable via `mcpServer`)
-- `AI_GATEWAY_API_KEY` environment variable
+- `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` at build time
 
 ## Customization
 

package/modules/assistant/index.ts

@@ -33,12 +33,14 @@ export default defineNuxtModule<AssistantModuleOptions>({
     model: 'google/gemini-3-flash',
   },
   setup(options, nuxt) {
-    const hasApiKey = !!process.env.AI_GATEWAY_API_KEY
+    const hasAiGatewayAuth = !!(
+      process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN
+    )
 
     const { resolve } = createResolver(import.meta.url)
 
     nuxt.options.runtimeConfig.public.assistant = {
-      enabled: hasApiKey,
+      enabled: hasAiGatewayAuth,
       apiPath: options.apiPath!,
     }
 
@@ -60,14 +62,14 @@ export default defineNuxtModule<AssistantModuleOptions>({
     components.forEach(name =>
       addComponent({
         name,
-        filePath: hasApiKey
+        filePath: hasAiGatewayAuth
           ? resolve(`./runtime/components/${name}.vue`)
           : resolve('./runtime/components/AssistantChatDisabled.vue'),
       }),
     )
 
-    if (!hasApiKey) {
-      log.warn('AI assistant disabled: AI_GATEWAY_API_KEY not found')
+    if (!hasAiGatewayAuth) {
+      log.warn('AI assistant disabled: neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN found')
       return
     }
 

package/modules/assistant/runtime/server/api/search.ts

@@ -37,6 +37,11 @@ function getSystemPrompt(siteName: string) {
 - Be concise, helpful, and direct
 - Guide users like a friendly expert would
 
+**Links and exploration:**
+- Tool results include a \`url\` for each page — prefer markdown links \`[label](url)\` so users can open the doc in one click
+- When it helps, add extra links (related pages, “read more”, side topics) — make the answer easy to dig into, not a wall of text
+- Stick to URLs from tool results (\`url\` / \`path\`) so links stay valid
+
 **FORMATTING RULES (CRITICAL):**
 - NEVER use markdown headings (#, ##, ###, etc.)
 - Use **bold text** for emphasis and section labels

package/modules/config.ts

@@ -58,13 +58,18 @@ export default defineNuxtModule({
       branch: getGitBranch(),
     })
 
+    const forcedColorMode = (nuxt.options.appConfig.docus as Record<string, unknown>)?.colorMode as string | undefined
+    if (forcedColorMode === 'light' || forcedColorMode === 'dark') {
+      nuxt.options.colorMode = defu({ preference: forcedColorMode, fallback: forcedColorMode }, nuxt.options.colorMode || {}) as typeof nuxt.options.colorMode
+    }
+
     /*
     ** I18N
     */
-    const typedNuxtOptions = nuxt.options as typeof nuxt.options & { i18n?: DocusI18nOptions }
+    const typedNuxtOptions = nuxt.options as typeof nuxt.options & { i18n?: false | DocusI18nOptions }
     const i18nOptions = typedNuxtOptions.i18n
 
-    if (i18nOptions?.locales) {
+    if (i18nOptions && typeof i18nOptions === 'object' && i18nOptions.locales) {
       const { resolve } = createResolver(import.meta.url)
 
       // Filter locales to only include existing ones

package/modules/skills/index.ts

@@ -0,0 +1,146 @@
+import { addServerHandler, createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+
+interface SkillEntry {
+  name: string
+  description: string
+  files: string[]
+}
+
+const SKILL_NAME_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+const MAX_NAME_LENGTH = 64
+
+const log = logger.withTag('Docus')
+
+export default defineNuxtModule({
+  meta: {
+    name: 'skills',
+  },
+  async setup(_options, nuxt) {
+    const skillsDir = join(nuxt.options.rootDir, 'skills')
+    if (!existsSync(skillsDir)) return
+
+    const catalog = await scanSkills(skillsDir)
+    if (!catalog.length) return
+
+    log.info(`Found ${catalog.length} agent skill${catalog.length > 1 ? 's' : ''}: ${catalog.map(s => s.name).join(', ')}`)
+
+    nuxt.options.runtimeConfig.skills = { catalog }
+
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.hook('nitro:config', (nitroConfig) => {
+      nitroConfig.serverAssets ||= []
+      nitroConfig.serverAssets.push({ baseName: 'skills', dir: skillsDir })
+
+      nitroConfig.prerender ||= {}
+      nitroConfig.prerender.routes ||= []
+      nitroConfig.prerender.routes.push('/.well-known/skills/index.json')
+      for (const skill of catalog) {
+        for (const file of skill.files) {
+          nitroConfig.prerender.routes.push(`/.well-known/skills/${skill.name}/${file}`)
+        }
+      }
+    })
+
+    addServerHandler({
+      route: '/.well-known/skills/index.json',
+      handler: resolve('./runtime/server/routes/skills-index'),
+    })
+
+    addServerHandler({
+      route: '/.well-known/skills/**',
+      handler: resolve('./runtime/server/routes/skills-files'),
+    })
+  },
+})
+
+function parseFrontmatter(content: string): { name?: string, description?: string } | null {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match?.[1]) return null
+  try {
+    return parseYaml(match[1])
+  }
+  catch {
+    return null
+  }
+}
+
+function validateSkillName(name: string, dirName: string): boolean {
+  if (name.length > MAX_NAME_LENGTH) {
+    log.warn(`Skill "${name}" exceeds ${MAX_NAME_LENGTH} character limit`)
+    return false
+  }
+  if (!SKILL_NAME_REGEX.test(name) || name.includes('--')) {
+    log.warn(`Skill name "${name}" does not match the Agent Skills naming spec`)
+    return false
+  }
+  if (name !== dirName) {
+    log.warn(`Skill name "${name}" does not match directory name "${dirName}"`)
+    return false
+  }
+  return true
+}
+
+async function listFilesRecursively(dir: string, base: string = ''): Promise<string[]> {
+  const files: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const relPath = base ? `${base}/${entry.name}` : entry.name
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursively(join(dir, entry.name), relPath))
+    }
+    else {
+      files.push(relPath)
+    }
+  }
+  return files
+}
+
+async function scanSkills(skillsDir: string): Promise<SkillEntry[]> {
+  const catalog: SkillEntry[] = []
+  const entries = await readdir(skillsDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+
+    const skillDir = join(skillsDir, entry.name)
+    const skillMdPath = join(skillDir, 'SKILL.md')
+
+    if (!existsSync(skillMdPath)) continue
+
+    const content = await readFile(skillMdPath, 'utf-8')
+    const frontmatter = parseFrontmatter(content)
+
+    if (!frontmatter?.description) {
+      log.warn(`Skipping skill "${entry.name}": missing description in SKILL.md frontmatter`)
+      continue
+    }
+
+    const name = frontmatter.name || entry.name
+    if (!validateSkillName(name, entry.name)) continue
+
+    const allFiles = await listFilesRecursively(skillDir)
+    const files = allFiles.filter(f => !f.split('/').some(s => s.startsWith('.')))
+    const sortedFiles = ['SKILL.md', ...files.filter(f => f !== 'SKILL.md')]
+
+    catalog.push({
+      name,
+      description: frontmatter.description,
+      files: sortedFiles,
+    })
+  }
+
+  return catalog
+}
+
+declare module 'nuxt/schema' {
+  interface RuntimeConfig {
+    skills: {
+      catalog: SkillEntry[]
+    }
+  }
+}

package/modules/skills/runtime/server/routes/skills-files.ts

@@ -0,0 +1,49 @@
+const CONTENT_TYPES: Record<string, string> = {
+  '.md': 'text/markdown; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.yaml': 'text/yaml; charset=utf-8',
+  '.yml': 'text/yaml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.py': 'text/plain; charset=utf-8',
+  '.sh': 'text/plain; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.ts': 'text/plain; charset=utf-8',
+}
+
+function getContentType(path: string): string {
+  const ext = path.slice(path.lastIndexOf('.'))
+  return CONTENT_TYPES[ext] || 'application/octet-stream'
+}
+
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event)
+  const prefix = '/.well-known/skills/'
+  const idx = url.pathname.indexOf(prefix)
+  if (idx === -1) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  const filePath = decodeURIComponent(url.pathname.slice(idx + prefix.length))
+
+  if (!filePath || filePath.includes('..')) {
+    throw createError({ statusCode: 400, statusMessage: 'Bad Request' })
+  }
+
+  const { skills } = useRuntimeConfig(event)
+  const skillName = filePath.split('/')[0]
+  if (!skills.catalog.some((s: { name: string }) => s.name === skillName)) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  const storage = useStorage('assets:skills')
+  const content = await storage.getItemRaw<string>(filePath)
+
+  if (!content) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  setResponseHeader(event, 'content-type', getContentType(filePath))
+  setResponseHeader(event, 'cache-control', 'public, max-age=3600')
+
+  return content
+})

package/modules/skills/runtime/server/routes/skills-index.ts

@@ -0,0 +1,8 @@
+export default defineEventHandler((event) => {
+  const { skills } = useRuntimeConfig(event)
+
+  setResponseHeader(event, 'content-type', 'application/json')
+  setResponseHeader(event, 'cache-control', 'public, max-age=3600')
+
+  return { skills: skills.catalog }
+})

package/nuxt.config.ts

@@ -10,6 +10,7 @@ export default defineNuxtConfig({
     resolve('./modules/config'),
     resolve('./modules/routing'),
     resolve('./modules/markdown-rewrite'),
+    resolve('./modules/skills'),
     resolve('./modules/css'),
     () => {
       const nuxt = useNuxt()
@@ -38,9 +39,11 @@ export default defineNuxtConfig({
 
         // Fix @vercel/oidc ESM export issue (transitive dep of @ai-sdk/gateway)
         // Only needed when AI assistant is enabled.
-        if (process.env.AI_GATEWAY_API_KEY) {
+        if (process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN) {
           config.optimizeDeps.include.push('@vercel/oidc')
-          config.optimizeDeps.include.map(id => id.replace(/^@vercel\/oidc$/, 'docus > @vercel/oidc'))
+          config.optimizeDeps.include = config.optimizeDeps.include.map(id =>
+            id.replace(/^@vercel\/oidc$/, 'docus > @vercel/oidc'),
+          )
         }
       })
     },
@@ -118,6 +121,9 @@ export default defineNuxtConfig({
     },
     provider: 'iconify',
   },
+  ogImage: {
+    zeroRuntime: true,
+  },
   robots: {
     groups: [
       {

package/nuxt.schema.ts

@@ -277,6 +277,28 @@ export default defineNuxtSchema({
         }),
       },
     }),
+    docus: group({
+      title: 'Docus',
+      description: 'Docus configuration.',
+      icon: 'i-lucide-settings',
+      fields: {
+        locale: field({
+          type: 'string',
+          title: 'Locale',
+          description: 'Default locale for single-language documentation.',
+          icon: 'i-lucide-languages',
+          default: 'en',
+        }),
+        colorMode: field({
+          type: 'string',
+          title: 'Color Mode',
+          description: 'Force a specific color mode. Leave empty for system preference with toggle.',
+          icon: 'i-lucide-monitor',
+          default: '',
+          required: ['', 'light', 'dark'],
+        }),
+      },
+    }),
     assistant: group({
       title: 'Assistant',
       description: 'Assistant configuration.',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docus",
   "description": "Nuxt layer for Docus documentation theme",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "repository": {
@@ -22,39 +22,41 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.66",
-    "@ai-sdk/mcp": "^1.0.25",
-    "@ai-sdk/vue": "3.0.116",
-    "@iconify-json/lucide": "^1.2.96",
-    "@iconify-json/simple-icons": "^1.2.73",
+    "@ai-sdk/gateway": "^3.0.83",
+    "@ai-sdk/mcp": "^1.0.30",
+    "@ai-sdk/vue": "3.0.141",
+    "@iconify-json/lucide": "^1.2.100",
+    "@iconify-json/simple-icons": "^1.2.75",
     "@iconify-json/vscode-icons": "^1.2.45",
     "@nuxt/content": "^3.12.0",
     "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.3.1",
-    "@nuxt/ui": "^4.5.1",
-    "@nuxtjs/i18n": "^10.2.3",
-    "@nuxtjs/mcp-toolkit": "^0.7.0",
-    "@nuxtjs/mdc": "^0.20.2",
-    "@nuxtjs/robots": "^5.7.1",
+    "@nuxt/kit": "^4.4.2",
+    "@nuxt/ui": "^4.6.0",
+    "@nuxtjs/i18n": "^10.2.4",
+    "@nuxtjs/mcp-toolkit": "^0.13.2",
+    "@nuxtjs/mdc": "^0.21.0",
+    "@nuxtjs/robots": "^6.0.6",
+    "@shikijs/core": "^4.0.2",
+    "@shikijs/engine-javascript": "^4.0.2",
+    "@shikijs/langs": "^4.0.2",
+    "@shikijs/themes": "^4.0.2",
+    "@takumi-rs/core": "^0.73.1",
     "@vueuse/core": "^14.2.1",
-    "ai": "6.0.116",
+    "ai": "6.0.141",
     "defu": "^6.1.4",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "motion-v": "^1.10.3",
+    "motion-v": "^2.2.0",
     "nuxt-llms": "^0.2.0",
-    "nuxt-og-image": "^5.1.13",
+    "nuxt-og-image": "^6.3.1",
     "pkg-types": "^2.3.0",
     "scule": "^1.3.0",
-    "@shikijs/core": "^3.22.0",
-    "@shikijs/engine-javascript": "^3.22.0",
-    "@shikijs/langs": "^3.22.0",
-    "@shikijs/themes": "^3.22.0",
     "shiki-stream": "^0.1.4",
-    "tailwindcss": "^4.2.1",
+    "tailwindcss": "^4.2.2",
     "ufo": "^1.6.3",
+    "yaml": "^2.7.1",
     "zod": "^4.3.6",
-    "zod-to-json-schema": "^3.25.1"
+    "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
     "better-sqlite3": "12.x",

package/server/mcp/tools/get-page.ts

@@ -17,9 +17,19 @@ WHEN NOT TO USE: If you don't know the exact path and need to search/explore, us
 
 WORKFLOW: This tool returns the complete page content including title, description, and full markdown. Use this when you need to provide detailed answers or code examples from specific documentation pages.
 `,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     path: z.string().describe('The page path from list-pages or provided by the user (e.g., /en/getting-started/installation)'),
   },
+  inputExamples: [
+    { path: '/en/getting-started/installation' },
+    { path: '/getting-started/introduction' },
+  ],
   cache: '1h',
   handler: async ({ path }) => {
     const event = useEvent()
@@ -38,21 +48,22 @@ WORKFLOW: This tool returns the complete page content including title, descripti
         .first()
 
       if (!page) {
-        return errorResult('Page not found')
+        throw createError({ statusCode: 404, message: 'Page not found' })
       }
 
       const content = await event.$fetch<string>(`/raw${path}.md`)
 
-      return jsonResult({
+      return {
         title: page.title,
         path: page.path,
         description: page.description,
         content,
         url: `${siteUrl}${page.path}`,
-      })
+      }
     }
-    catch {
-      return errorResult('Failed to get page')
+    catch (error) {
+      if ((error as { statusCode?: number }).statusCode === 404) throw error
+      throw createError({ statusCode: 500, message: 'Failed to get page' })
     }
   },
 })

package/server/mcp/tools/list-pages.ts

@@ -23,9 +23,19 @@ OUTPUT: Returns a structured list with:
 - path: Exact path for use with get-page
 - description: Brief summary of page content
 - url: Full URL for reference`,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
-    locale: z.string().optional().describe('The locale to filter pages by'),
+    locale: z.string().optional().describe('The locale to filter pages by (e.g., "en", "fr")'),
   },
+  inputExamples: [
+    { locale: 'en' },
+    {},
+  ],
   cache: '1h',
   handler: async ({ locale }) => {
     const event = useEvent()
@@ -52,10 +62,10 @@ OUTPUT: Returns a structured list with:
         }),
       )
 
-      return jsonResult(allPages.flat())
+      return allPages.flat()
     }
     catch {
-      return errorResult('Failed to list pages')
+      throw createError({ statusCode: 500, message: 'Failed to list pages' })
     }
   },
 })

package/app/components/OgImage/OgImageDocs.vue

@@ -1,76 +0,0 @@
-<script lang="ts" setup>
-const props = withDefaults(defineProps<{ title?: string, description?: string, headline?: string }>(), {
-  title: 'title',
-  description: 'description',
-})
-
-const title = (props.title || '').slice(0, 60)
-const description = (props.description || '').slice(0, 200)
-</script>
-
-<template>
-  <div class="w-full h-full flex flex-col justify-center bg-neutral-900">
-    <svg
-      class="absolute right-0 top-0 opacity-50"
-      width="629"
-      height="593"
-      viewBox="0 0 629 593"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <g filter="url(#filter0_f_199_94966)">
-        <path
-          d="M628.5 -578L639.334 -94.4223L806.598 -548.281L659.827 -87.387L965.396 -462.344L676.925 -74.0787L1087.69 -329.501L688.776 -55.9396L1160.22 -164.149L694.095 -34.9354L1175.13 15.7948L692.306 -13.3422L1130.8 190.83L683.602 6.50012L1032.04 341.989L668.927 22.4412L889.557 452.891L649.872 32.7537L718.78 511.519L628.5 36.32L538.22 511.519L607.128 32.7537L367.443 452.891L588.073 22.4412L224.955 341.989L573.398 6.50012L126.198 190.83L564.694 -13.3422L81.8734 15.7948L562.905 -34.9354L96.7839 -164.149L568.224 -55.9396L169.314 -329.501L580.075 -74.0787L291.604 -462.344L597.173 -87.387L450.402 -548.281L617.666 -94.4223L628.5 -578Z"
-          fill="white"
-        />
-      </g>
-      <defs>
-        <filter
-          id="filter0_f_199_94966"
-          x="0.873535"
-          y="-659"
-          width="1255.25"
-          height="1251.52"
-          filterUnits="userSpaceOnUse"
-          color-interpolation-filters="sRGB"
-        >
-          <feFlood
-            flood-opacity="0"
-            result="BackgroundImageFix"
-          />
-          <feBlend
-            mode="normal"
-            in="SourceGraphic"
-            in2="BackgroundImageFix"
-            result="shape"
-          />
-          <feGaussianBlur
-            stdDeviation="40.5"
-            result="effect1_foregroundBlur_199_94966"
-          />
-        </filter>
-      </defs>
-    </svg>
-
-    <div class="pl-[100px]">
-      <p
-        v-if="headline"
-        class="uppercase text-[24px] text-emerald-500 mb-4 font-semibold"
-      >
-        {{ headline }}
-      </p>
-      <h1
-        v-if="title"
-        class="m-0 text-[75px] font-semibold mb-4 text-white flex items-center"
-      >
-        <span>{{ title }}</span>
-      </h1>
-      <p
-        v-if="description"
-        class="text-[32px] text-neutral-300 leading-tight w-[700px]"
-      >
-        {{ description }}
-      </p>
-    </div>
-  </div>
-</template>

package/app/components/OgImage/OgImageLanding.vue

@@ -1,98 +0,0 @@
-<script lang="ts" setup>
-const props = withDefaults(defineProps<{ title?: string, description?: string }>(), {
-  title: 'title',
-  description: 'description',
-})
-
-const appConfig = useAppConfig()
-const logoPath = appConfig.header?.logo?.dark || appConfig.header?.logo?.light
-
-const logoSvg = await fetchLogoSvg(logoPath)
-
-const title = (props.title || '').slice(0, 60)
-const description = (props.description || '').slice(0, 200)
-
-async function fetchLogoSvg(path?: string): Promise<string> {
-  if (!path) return ''
-  try {
-    // eslint-disable-next-line
-    // @ts-ignore
-    const { url: siteUrl } = useSiteConfig()
-    const url = path.startsWith('http') ? path : `${siteUrl}${path}`
-    const svg = await $fetch<string>(url, { responseType: 'text' })
-    return svg.replace('<svg', '<svg width="100%" height="100%"')
-  }
-  catch {
-    return ''
-  }
-}
-</script>
-
-<template>
-  <div class="w-full h-full flex items-center justify-center bg-neutral-900">
-    <svg
-      class="absolute right-0 top-0 opacity-50"
-      width="629"
-      height="593"
-      viewBox="0 0 629 593"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <g filter="url(#filter0_f_199_94966)">
-        <path
-          d="M628.5 -578L639.334 -94.4223L806.598 -548.281L659.827 -87.387L965.396 -462.344L676.925 -74.0787L1087.69 -329.501L688.776 -55.9396L1160.22 -164.149L694.095 -34.9354L1175.13 15.7948L692.306 -13.3422L1130.8 190.83L683.602 6.50012L1032.04 341.989L668.927 22.4412L889.557 452.891L649.872 32.7537L718.78 511.519L628.5 36.32L538.22 511.519L607.128 32.7537L367.443 452.891L588.073 22.4412L224.955 341.989L573.398 6.50012L126.198 190.83L564.694 -13.3422L81.8734 15.7948L562.905 -34.9354L96.7839 -164.149L568.224 -55.9396L169.314 -329.501L580.075 -74.0787L291.604 -462.344L597.173 -87.387L450.402 -548.281L617.666 -94.4223L628.5 -578Z"
-          fill="white"
-        />
-      </g>
-      <defs>
-        <filter
-          id="filter0_f_199_94966"
-          x="0.873535"
-          y="-659"
-          width="1255.25"
-          height="1251.52"
-          filterUnits="userSpaceOnUse"
-          color-interpolation-filters="sRGB"
-        >
-          <feFlood
-            flood-opacity="0"
-            result="BackgroundImageFix"
-          />
-          <feBlend
-            mode="normal"
-            in="SourceGraphic"
-            in2="BackgroundImageFix"
-            result="shape"
-          />
-          <feGaussianBlur
-            stdDeviation="40.5"
-            result="effect1_foregroundBlur_199_94966"
-          />
-        </filter>
-      </defs>
-    </svg>
-
-    <div
-      class="flex flex-col items-center justify-center p-8"
-    >
-      <div
-        v-if="logoSvg"
-        class="flex items-center justify-center mb-10 max-w-[900px]"
-        style="width: 72px; height: 72px;"
-        v-html="logoSvg"
-      />
-      <h1
-        v-if="title"
-        class="m-0 text-5xl font-semibold mb-4 text-white text-center"
-      >
-        {{ title }}
-      </h1>
-      <p
-        v-if="description"
-        class="text-center text-2xl text-neutral-300 leading-tight max-w-[800px]"
-      >
-        {{ description }}
-      </p>
-    </div>
-  </div>
-</template>