diff --git a/.vitepress/config/community.ts b/.vitepress/config/community.ts
index 1f530fe3a..bad997cc5 100644
--- a/.vitepress/config/community.ts
+++ b/.vitepress/config/community.ts
@@ -26,7 +26,7 @@ export function community(words: Words, prefix = '', videos: 'youtube' | 'bilibi
         text: words.connect,
         items: [
           row('Discord', LINKS.discord, 'icon-[simple-icons--discord]', '#5865F2'),
-          row('X', LINKS.x, 'icon-[simple-icons--x]', '#000000')
+          row('X', LINKS.x, 'icon-[simple-icons--x]')
         ]
       },
       {
diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts
index f92d6a907..575fea8b7 100644
--- a/.vitepress/config/en.ts
+++ b/.vitepress/config/en.ts
@@ -89,6 +89,7 @@ export const config = defineConfig({
       next: 'Next page'
     },
     outline: {
+      level: [2, 3],
       label: 'On this page'
     },
     lastUpdated: {
diff --git a/.vitepress/config/goravel-code.ts b/.vitepress/config/goravel-code.ts
index 051585ec7..094ca1763 100644
--- a/.vitepress/config/goravel-code.ts
+++ b/.vitepress/config/goravel-code.ts
@@ -1,26 +1,34 @@
 import type { ThemeOptions } from 'vitepress'
 
-const INK = '#101820'
-const GREY = '#68747d'
-const CYAN = '#0077b3'
-const RED = '#b02b2b'
+interface Palette {
+  ink: string
+  grey: string
+  cyan: string
+  red: string
+}
+
+// These palettes mirror the light and dark values of the theme tokens in
+// .vitepress/theme/goravel.css: ink -> --g-ink, grey -> --g-grey,
+// cyan -> --g-cyan-text, red -> --g-red-text. Keep them in step.
+const LIGHT: Palette = { ink: '#101820', grey: '#636f78', cyan: '#0074ae', red: '#b02b2b' }
+const DARK: Palette = { ink: '#e6edf2', grey: '#8a99a5', cyan: '#5cc4f7', red: '#f59393' }
 
 const rule = (scope: string[], foreground: string) => ({ scope, settings: { foreground } })
 
-export const goravelCode: ThemeOptions = {
-  name: 'goravel',
-  type: 'light',
+const theme = (type: 'light' | 'dark', { ink, grey, cyan, red }: Palette) => ({
+  name: `goravel-${type}`,
+  type,
   // transparent, so a callout's lighter ground shows through
-  colors: { 'editor.background': '#00000000', 'editor.foreground': INK },
+  colors: { 'editor.background': '#00000000', 'editor.foreground': ink },
   tokenColors: [
-    { settings: { foreground: INK } },
-    rule(['comment', 'punctuation.definition.comment', 'string.comment'], GREY),
-    rule(['keyword', 'storage', 'constant.language', 'variable.language'], INK),
-    rule(['entity.name.function', 'support.function', 'entity.name.command'], CYAN),
-    rule(['string', 'constant.numeric', 'constant.character'], GREY),
-    rule(['punctuation', 'keyword.operator', 'meta.brace'], GREY),
-    rule(['markup.inserted', 'meta.diff.header.to-file'], CYAN),
-    rule(['markup.deleted', 'meta.diff.header.from-file'], RED),
+    { settings: { foreground: ink } },
+    rule(['comment', 'punctuation.definition.comment', 'string.comment'], grey),
+    rule(['keyword', 'storage', 'constant.language', 'variable.language'], ink),
+    rule(['entity.name.function', 'support.function', 'entity.name.command'], cyan),
+    rule(['string', 'constant.numeric', 'constant.character'], grey),
+    rule(['punctuation', 'keyword.operator', 'meta.brace'], grey),
+    rule(['markup.inserted', 'meta.diff.header.to-file'], cyan),
+    rule(['markup.deleted', 'meta.diff.header.from-file'], red),
     // narrower scopes that override the grey and cyan rules above
     rule(
       [
@@ -28,9 +36,11 @@ export const goravelCode: ThemeOptions = {
         'support.type', 'support.class', 'storage.type.numeric.go', 'storage.type.string.go',
         'storage.type.boolean.go', 'storage.type.byte.go', 'storage.type.error.go',
         'variable', 'meta.definition.variable', 'punctuation.definition.variable.php',
-        'string.unquoted.argument.shell', 'constant.other.option'
+        'string.unquoted.argument.shell', 'constant.other.option', 'entity.name.tag.yaml'
       ],
-      INK
+      ink
     )
   ]
-}
+})
+
+export const goravelCode: ThemeOptions = { light: theme('light', LIGHT), dark: theme('dark', DARK) }
diff --git a/.vitepress/config/shared.ts b/.vitepress/config/shared.ts
index bf48bcf00..f23b866f4 100644
--- a/.vitepress/config/shared.ts
+++ b/.vitepress/config/shared.ts
@@ -40,7 +40,9 @@ function liftFileNames(md: MarkdownRenderer) {
   const fence = md.renderer.rules.fence!
   md.renderer.rules.fence = (tokens, idx, options, env, self) => {
     const token = tokens[idx]
-    const path = token.content.match(/^(?:\/\/|#|--) ?([\w.@-]+(?:\/[\w.@-]+)*\.\w+)\n/)
+    // a demo holds markdown, not one code block, so its first line is never a file name
+    if (/^md\s+demo\b/.test(token.info.trim())) return fence(tokens, idx, options, env, self)
+    const path = token.content.match(/^(?:\/\/|#|--) ?((?:[\w.@-]+\/)*[\w.@-]*\.\w+)\n/)
     // line highlights like {2,4} count from the first line, so a block using them keeps it
     if (!path || /\{[\d,-]+\}/.test(token.info)) return fence(tokens, idx, options, env, self)
     token.content = token.content.slice(path[0].length)
@@ -48,6 +50,19 @@ function liftFileNames(md: MarkdownRenderer) {
   }
 }
 
+// a fence opened as ````md demo shows its source and then renders it, so an example is written once;
+// the rendered headings are kept out of the outline
+function renderDemos(md: MarkdownRenderer) {
+  const fence = md.renderer.rules.fence!
+  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const source = fence(tokens, idx, options, env, self)
+    if (!/^md\s+demo\b/.test(tokens[idx].info.trim())) return source
+    // a demo teaches syntax, so a link in it is illustrative; keep it out of the page's dead-link check
+    // (VitePress's link plugin pushes into env.links)
+    return source + md.render(tokens[idx].content, { ...env, links: [] }).replace(/<h([1-6])(?![^>]*\bclass=)/g, '<h$1 class="ignore-header"')
+  }
+}
+
 // a percentage in the packages table's coverage column gets a bar beside it when the page is built
 function drawCoverageBars(md: MarkdownRenderer) {
   const close = md.renderer.rules.td_close ?? ((tokens, idx, options, _env, self) => self.renderToken(tokens, idx, options))
@@ -66,9 +81,9 @@ export const shared = defineConfig({
   rewrites: {
     'en/:rest*': ':rest*'
   },
+  srcExclude: ['**/README.md', '**/AGENTS.md'],
 
-  // there is no dark design
-  appearance: false,
+  appearance: true,
   lastUpdated: true,
   cleanUrls: false,
   metaChunk: true,
@@ -117,6 +132,7 @@ export const shared = defineConfig({
       md.use(deflist)
       markCustomContainerTitles(md)
       liftFileNames(md)
+      renderDemos(md)
       drawCoverageBars(md)
     },
     languages: ['go']
diff --git a/.vitepress/config/zh_CN.ts b/.vitepress/config/zh_CN.ts
index 5180fe9a1..07150e006 100644
--- a/.vitepress/config/zh_CN.ts
+++ b/.vitepress/config/zh_CN.ts
@@ -74,6 +74,7 @@ export const config = defineConfig({
       next: "下一页"
     },
     outline: {
+      level: [2, 3],
       label: "页面导航"
     },
     lastUpdated: {
diff --git a/.vitepress/theme/Layout.vue b/.vitepress/theme/Layout.vue
index 5ee90bc50..d4be1a10f 100644
--- a/.vitepress/theme/Layout.vue
+++ b/.vitepress/theme/Layout.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import DefaultTheme from 'vitepress/theme-without-fonts'
 import DocMeta from './components/DocMeta.vue'
-import MethodIndex from './components/MethodIndex.vue'
 import NotFound from './components/NotFound.vue'
 import DocsFooterLinks from './components/DocsFooterLinks.vue'
 
@@ -11,7 +10,6 @@ const { Layout } = DefaultTheme
 <template>
   <Layout>
     <template #doc-before><DocMeta /></template>
-    <template #aside-outline-after><MethodIndex /></template>
     <template #not-found><NotFound /></template>
     <template #layout-bottom><DocsFooterLinks /></template>
   </Layout>
diff --git a/.vitepress/theme/components/Brand.vue b/.vitepress/theme/components/Brand.vue
index e9baa8e73..1172094aa 100644
--- a/.vitepress/theme/components/Brand.vue
+++ b/.vitepress/theme/components/Brand.vue
@@ -10,7 +10,7 @@ defineProps<{ laravel?: boolean; goravel?: boolean; no?: boolean }>()
   </span>
 </template>
 
-<style>
+<style scoped>
 .brand {
   display: inline-flex;
   align-items: center;
@@ -22,7 +22,7 @@ defineProps<{ laravel?: boolean; goravel?: boolean; no?: boolean }>()
 .brand-mark {
   width: 14px;
   height: 14px;
-  color: #ff2d20;
+  color: var(--g-laravel);
 }
 
 .brand-state {
diff --git a/.vitepress/theme/components/MethodIndex.vue b/.vitepress/theme/components/MethodIndex.vue
deleted file mode 100644
index 58c8307c4..000000000
--- a/.vitepress/theme/components/MethodIndex.vue
+++ /dev/null
@@ -1,141 +0,0 @@
-<script setup lang="ts">
-import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
-import { useRoute } from 'vitepress'
-import { useI18n } from '../i18n'
-
-const route = useRoute()
-const { tr } = useI18n()
-const methods = ref<{ id: string; name: string }[]>([])
-const query = ref('')
-const active = ref('')
-const shown = computed(() => methods.value.filter((m) => m.name.toLowerCase().includes(query.value.toLowerCase())))
-let observer: IntersectionObserver | undefined
-
-// `After`, `path.App()`
-const CODE_NAME = /^[\w.]+(\(\))?$/
-// WithSession, Where / OrWhere; a plain word like Cursor is a section, not a method
-const HEADING_NAME = /^([A-Z][a-z]+[A-Z]\w*|[A-Z]\w*( \/ [A-Z]\w*)+)$/
-// **Latest**
-const BOLD_NAME = /^[A-Z]\w*( \/ [A-Z]\w*)*$/
-
-function methodName(el: HTMLElement) {
-  const name = (el.textContent ?? '').replace(/[\u200b#:]/g, '').trim()
-  if (el.tagName === 'P') return BOLD_NAME.test(name) ? name : null
-  if (el.querySelector(':scope > code')) return CODE_NAME.test(name) ? name : null
-  return HEADING_NAME.test(name) ? name : null
-}
-
-function collect() {
-  observer?.disconnect()
-  const found = new Map<string, HTMLElement>()
-  for (const node of document.querySelectorAll<HTMLElement>('.vp-doc h3, .vp-doc h4, .vp-doc p > strong:only-child')) {
-    const el = node.tagName === 'STRONG' ? node.parentElement! : node
-    const name = methodName(el)
-    if (name && !found.has(name)) found.set(name, el)
-  }
-  methods.value = []
-  if (found.size < 6) return
-
-  observer = new IntersectionObserver(
-    (entries) => {
-      const visible = entries.find((entry) => entry.isIntersecting)
-      if (visible) active.value = visible.target.id
-    },
-    { rootMargin: '-80px 0px -70% 0px' }
-  )
-  for (const [name, el] of found) {
-    el.id ||= 'method-' + name.toLowerCase().replace(/\W+/g, '-')
-    observer.observe(el)
-    methods.value.push({ id: el.id, name })
-  }
-}
-
-onMounted(collect)
-onUnmounted(() => observer?.disconnect())
-watch(() => route.path, () => nextTick(collect))
-</script>
-
-<template>
-  <div v-if="methods.length" class="goravel-methods">
-    <div class="outline-title">{{ tr('Methods') }}</div>
-    <input
-      v-if="methods.length >= 14"
-      v-model="query"
-      class="filter"
-      type="search"
-      :placeholder="tr('Filter')"
-      :aria-label="tr('Filter methods')"
-    />
-    <a
-      v-for="method in shown"
-      :key="method.id"
-      class="method"
-      :class="{ active: method.id === active }"
-      :href="`#${method.id}`"
-    >{{ method.name }}</a>
-  </div>
-</template>
-
-<style scoped>
-.goravel-methods {
-  display: flex;
-  flex-direction: column;
-  margin-bottom: 28px;
-  padding: 0 var(--g-shell-inset) 0 var(--g-rail);
-}
-
-.filter {
-  width: 100%;
-  height: 30px;
-  margin: 0 0 6px;
-  padding: 0 10px;
-  border-radius: 2px;
-  background: var(--g-soft);
-  font-size: 13px;
-  color: var(--g-ink);
-  transition: background-color 0.15s ease, box-shadow 0.15s ease;
-}
-
-.filter::placeholder {
-  color: var(--g-grey);
-}
-
-.filter:hover {
-  background: var(--g-hover);
-}
-
-.filter:focus {
-  outline: none;
-  background: var(--g-white);
-  box-shadow: inset 0 0 0 1px var(--g-cyan);
-}
-
-.method {
-  position: relative;
-  padding: 2px 0 2px 12px;
-  font-family: var(--vp-font-family-mono);
-  font-size: 12px;
-  line-height: 18px;
-  overflow-wrap: anywhere;
-  color: var(--g-grey);
-  transition: color 0.15s ease;
-}
-
-.method:hover {
-  color: var(--g-ink);
-}
-
-.method.active {
-  color: var(--g-cyan-text);
-}
-
-.method.active::before {
-  content: '';
-  position: absolute;
-  left: 0;
-  top: 5px;
-  bottom: 5px;
-  width: 2px;
-  background: var(--g-cyan);
-}
-</style>
diff --git a/.vitepress/theme/components/NavBar.vue b/.vitepress/theme/components/NavBar.vue
index 69fee9b93..9e103e406 100644
--- a/.vitepress/theme/components/NavBar.vue
+++ b/.vitepress/theme/components/NavBar.vue
@@ -15,9 +15,9 @@ import SelectMenu from './SelectMenu.vue'
 defineProps<{ isScreenOpen: boolean }>()
 defineEmits<{ (e: 'toggle-screen'): void }>()
 
-const { theme, localeIndex } = useData()
+const { theme, localeIndex, isDark } = useData()
 const { hasSidebar } = useSidebar()
-const { languages, currentLang } = useI18n()
+const { tr, languages, currentLang } = useI18n()
 const route = useRoute()
 
 const home = computed(() => (localeIndex.value === 'root' ? '/' : `/${localeIndex.value}/`))
@@ -67,6 +67,9 @@ const onFocusOut = useDismiss(navRoot, () => (menuOpen.value = false))
     <div class="utils">
       <SelectMenu v-if="hasSidebar" :label="version" :options="VERSIONS" />
       <SelectMenu class="lang" :label="currentLang.label!" :options="languages" />
+      <button type="button" class="theme" :aria-label="tr('Switch theme')" @click="isDark = !isDark">
+        <span class="sun icon-[lucide--sun]" /><span class="moon icon-[lucide--moon]" />
+      </button>
       <VPSocialLinks class="social" :links="theme.socialLinks ?? []" />
     </div>
 
@@ -178,7 +181,7 @@ const onFocusOut = useDismiss(navRoot, () => (menuOpen.value = false))
   padding: 0 var(--g-shell-inset);
   border-bottom: 1px solid var(--g-line);
   background: var(--g-white);
-  box-shadow: 0 24px 40px -24px rgba(16, 24, 32, 0.12);
+  box-shadow: 0 24px 40px -24px rgba(var(--g-shadow), 0.12);
 }
 
 .group {
@@ -300,6 +303,37 @@ const onFocusOut = useDismiss(navRoot, () => (menuOpen.value = false))
   margin-left: 20px;
 }
 
+.theme {
+  display: grid;
+  place-items: center;
+  width: var(--g-control);
+  height: var(--g-control);
+  margin: 0 -8px 0 -6px;
+  border-radius: 2px;
+  color: var(--g-grey);
+}
+
+.theme:hover {
+  color: var(--g-ink);
+}
+
+.theme span {
+  width: 17px;
+  height: 17px;
+}
+
+.moon {
+  display: none;
+}
+
+:global(.dark .bar .theme .sun) {
+  display: none;
+}
+
+:global(.dark .bar .theme .moon) {
+  display: block;
+}
+
 .social {
   margin-left: 2px;
 }
diff --git a/.vitepress/theme/components/NotFound.vue b/.vitepress/theme/components/NotFound.vue
index 651989c67..9770034d4 100644
--- a/.vitepress/theme/components/NotFound.vue
+++ b/.vitepress/theme/components/NotFound.vue
@@ -67,15 +67,18 @@ const suggestions = [
   height: 46px;
   margin-top: 28px;
   padding: 0 22px;
+  border: 1px solid transparent;
   border-radius: 2px;
-  background: var(--g-cyan);
+  background: var(--g-cyan-text);
   font-size: 15px;
   font-weight: 600;
-  color: var(--g-white);
+  color: var(--g-on-accent);
 }
 
 .home:hover {
-  background: var(--g-cyan-text);
+  border-color: var(--g-cyan-text);
+  background: var(--g-white);
+  color: var(--g-cyan-text);
 }
 
 .right {
diff --git a/.vitepress/theme/components/SelectMenu.vue b/.vitepress/theme/components/SelectMenu.vue
index 0ab6adf14..dd8b2409d 100644
--- a/.vitepress/theme/components/SelectMenu.vue
+++ b/.vitepress/theme/components/SelectMenu.vue
@@ -68,7 +68,7 @@ const onFocusOut = useDismiss(root, () => (open.value = false))
   border: 1px solid var(--g-line);
   border-radius: 2px;
   background: var(--g-white);
-  box-shadow: 0 4px 12px rgba(16, 24, 32, 0.06);
+  box-shadow: 0 4px 12px rgba(var(--g-shadow), 0.06);
 }
 
 .option {
diff --git a/.vitepress/theme/goravel.css b/.vitepress/theme/goravel.css
index ddc8db6ea..8a6b82e69 100644
--- a/.vitepress/theme/goravel.css
+++ b/.vitepress/theme/goravel.css
@@ -1,14 +1,24 @@
 :root {
   --g-white: #ffffff;
   --g-soft: #f7f9fa;
+  --g-code: #f7f9fa;
   --g-hover: #eef2f5;
   --g-ink: #101820;
-  --g-grey: #68747d;
+  --g-grey: #636f78;
+  --g-grey-strong: #5b6770;
   --g-line: #e5eaed;
+  --g-control-line: #e5eaed;
   --g-cyan: #009fe8;
-  --g-cyan-text: #0077b3;
+  --g-cyan-text: #0074ae;
   --g-cyan-tint: #ebf7fd;
   --g-construct: rgba(104, 116, 125, 0.4);
+  --g-on-accent: #ffffff;
+  --g-link-rule: rgba(0, 116, 174, 0.32);
+  --g-glass: rgba(255, 255, 255, 0.66);
+  --g-glass-strong: rgba(255, 255, 255, 0.72);
+  --g-scrim: rgba(16, 24, 32, 0.32);
+  --g-shadow: 16, 24, 32;
+  --g-laravel: #ff2d20;
 
   --g-amber: #e08700;
   --g-amber-text: #8f5a00;
@@ -48,6 +58,8 @@
 
   --vp-code-block-color: var(--g-ink);
   --vp-code-line-highlight-color: var(--g-cyan-tint);
+  --vp-code-line-warning-color: var(--g-amber-tint);
+  --vp-code-line-error-color: var(--g-red-tint);
   --vp-code-line-number-color: var(--g-grey);
   --vp-code-copy-code-hover-bg: var(--g-white);
   --vp-code-tab-divider: var(--g-line);
@@ -59,13 +71,40 @@
   --vp-sidebar-width: 272px;
 }
 
+.dark {
+  color-scheme: dark;
+
+  --g-white: #0d141b;
+  --g-soft: #121b24;
+  --g-code: #0a0f15;
+  --g-hover: #19242f;
+  --g-ink: #e6edf2;
+  --g-grey: #8a99a5;
+  --g-grey-strong: #93a2ad;
+  --g-line: #222f3b;
+  --g-control-line: #46576a;
+  --g-cyan-text: #5cc4f7;
+  --g-cyan-tint: #0f2b3d;
+  --g-construct: rgba(138, 153, 165, 0.34);
+  --g-on-accent: #0b1218;
+  --g-link-rule: rgba(92, 196, 247, 0.4);
+  --g-glass: rgba(13, 20, 27, 0.5);
+  --g-glass-strong: rgba(13, 20, 27, 0.6);
+  --g-scrim: rgba(0, 0, 0, 0.6);
+  --g-shadow: 0, 0, 0;
+
+  --g-amber-text: #f2b765;
+  --g-amber-tint: #2a2113;
+  --g-red-text: #f59393;
+  --g-red-tint: #2e181a;
+}
+
 /* ------------------------------------------------------------------ labels and marks */
 .g-label,
 .vp-doc .custom-block .custom-block-title,
 .vp-doc th,
 .vp-doc .footnotes::before,
 .VPDocAsideOutline .outline-title,
-.goravel-methods .outline-title,
 .VPNavScreenMenuGroupSection .title {
   font-family: var(--vp-font-family-mono);
   font-size: 12px;
@@ -85,7 +124,6 @@
 .g-diamond::before,
 .vp-doc .custom-block .custom-block-title::before,
 .VPDocAsideOutline .outline-title::before,
-.goravel-methods .outline-title::before,
 .VPNavScreenMenuGroupSection .title::before,
 .VPSidebarItem.level-1.is-active > .item::before,
 .VPDocOutlineItem .outline-link.active::before {
@@ -200,7 +238,7 @@
 
 .vp-doc a {
   font-weight: 400;
-  text-decoration: underline 1px rgba(0, 119, 179, 0.32);
+  text-decoration: underline 1px var(--g-link-rule);
   text-underline-offset: 3px;
 }
 
@@ -211,7 +249,7 @@
 .vp-doc :not(pre) > code {
   padding: 2px 6px;
   border-radius: 0;
-  background: var(--g-soft);
+  background: var(--g-code);
   font-size: 14px;
   color: var(--g-ink);
 }
@@ -246,7 +284,7 @@
 /* ------------------------------------------------------------------ code */
 /* The ground and rules are painted past the box, so the text keeps the article's edge. */
 .vp-doc {
-  --g-code-ground: var(--g-soft);
+  --g-code-ground: var(--g-code);
   --g-code-left: var(--g-left);
   --g-code-right: var(--g-right);
 }
@@ -521,7 +559,7 @@
 }
 
 .vp-doc .custom-block {
-  --g-code-ground: rgba(255, 255, 255, 0.66);
+  --g-code-ground: var(--g-glass);
   padding-top: 16px;
   padding-bottom: 18px;
   border-radius: 0;
@@ -600,17 +638,31 @@
 }
 
 .vp-doc .custom-block code {
-  background: rgba(255, 255, 255, 0.72);
+  background: var(--g-glass-strong);
 }
 
 .vp-doc .custom-block.info code {
-  background: var(--g-soft);
+  background: var(--g-code);
 }
 
 .vp-doc .custom-block div[class*='language-'],
 .vp-doc .custom-block .vp-code-group {
   margin-top: 14px;
   margin-bottom: 14px;
+  border-radius: 0;
+}
+
+.vp-doc .custom-block .vp-code-group .tabs {
+  border-radius: 0;
+}
+
+.vp-doc .custom-block:has(> div[class*='language-']:last-child, > .vp-code-group:last-child) {
+  padding-bottom: 0;
+}
+
+.vp-doc .custom-block > div[class*='language-']:last-child,
+.vp-doc .custom-block > .vp-code-group:last-child {
+  margin-bottom: 0;
 }
 
 .vp-doc .custom-block.details {
@@ -730,6 +782,7 @@
 }
 
 .vp-doc th {
+  overflow-wrap: normal;
   padding: 0 24px 10px 0;
   background: transparent;
   text-align: left;
@@ -759,7 +812,8 @@
   overflow-wrap: anywhere;
 }
 
-.vp-doc td:first-child > a {
+.vp-doc td:first-child > a,
+.vp-doc td:first-child > code {
   overflow-wrap: normal;
 }
 
@@ -861,7 +915,7 @@
   width: 15px;
   height: 15px;
   margin: 7px 0 0;
-  border: 1.5px solid var(--g-line);
+  border: 1.5px solid var(--g-control-line);
   border-radius: 2px;
   background: var(--g-white) center / 11px no-repeat;
 }
@@ -977,3 +1031,45 @@
 :lang(zh) .g-home .g-h2 {
   line-height: 1.25;
 }
+
+/* ------------------------------------------------------------------ keys and badges */
+.vp-doc kbd {
+  padding: 1px 6px;
+  border: 1px solid var(--g-control-line);
+  border-bottom-width: 2px;
+  border-radius: 2px;
+  background: var(--g-code);
+  font-family: var(--vp-font-family-mono);
+  font-size: 13px;
+}
+
+.vp-doc .VPBadge {
+  padding: 0 6px;
+  border: 0;
+  border-radius: 2px;
+  font-family: var(--vp-font-family-mono);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.vp-doc .VPBadge.info {
+  background: var(--g-hover);
+  color: var(--g-ink);
+}
+
+.vp-doc .VPBadge.tip {
+  background: var(--g-cyan-tint);
+  color: var(--g-cyan-text);
+}
+
+.vp-doc .VPBadge.warning {
+  background: var(--g-amber-tint);
+  color: var(--g-amber-text);
+}
+
+.vp-doc .VPBadge.danger {
+  background: var(--g-red-tint);
+  color: var(--g-red-text);
+}
diff --git a/.vitepress/theme/home/GoravelMark.vue b/.vitepress/theme/home/GoravelMark.vue
index 8b6dddfa7..bd691ff98 100644
--- a/.vitepress/theme/home/GoravelMark.vue
+++ b/.vitepress/theme/home/GoravelMark.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
-import { computed, useId } from 'vue'
+import { computed, nextTick, onMounted, ref, useId, watch } from 'vue'
+import { useData } from 'vitepress'
 import { Motion, MotionConfig } from 'motion-v'
 import type { PieceKey, PieceState } from './config'
 import { data as mark } from './mark.data'
@@ -52,10 +53,26 @@ const lattice = computed(() => {
   return lines.join('')
 })
 
+const { isDark } = useData()
+const ground = ref([255, 255, 255])
+// the fallback mirrors --g-grey-strong, which .g-home maps --g-grey to
+const outline = ref([91, 103, 112])
+const rgb = (hex: string) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16))
+const read = () => {
+  // .g-home raises --g-grey to --g-grey-strong, so read the mark's own scope
+  const scope = document.querySelector('.g-home') ?? document.documentElement
+  const style = getComputedStyle(scope)
+  ground.value = rgb(style.getPropertyValue('--g-white').trim())
+  outline.value = rgb(style.getPropertyValue('--g-grey').trim())
+}
+onMounted(read)
+watch(isDark, () => nextTick(read))
+
 const tint = (fill: string, amount: number) => {
   const value = parseInt(fill.slice(1), 16)
-  const channel = (shift: number) => Math.round((((value >> shift) & 255) - 255) * amount + 255)
-  return `rgb(${channel(16)}, ${channel(8)}, ${channel(0)})`
+  const channel = (shift: number, base: number) => Math.round((((value >> shift) & 255) - base) * amount + base)
+  const [r, g, b] = ground.value
+  return `rgb(${channel(16, r)}, ${channel(8, g)}, ${channel(0, b)})`
 }
 
 const stateOf = (key: PieceKey) => props.states[key] ?? 'solid'
@@ -64,8 +81,8 @@ const isPulled = (key: PieceKey) => props.pulled?.includes(key) ?? false
 function paint(piece: { key: PieceKey; fill: string }) {
   const state = stateOf(piece.key)
   return {
-    fill: state === 'ghost' ? 'rgba(255, 255, 255, 0)' : state === 'dim' ? tint(piece.fill, 0.28) : piece.fill,
-    stroke: `rgba(104, 116, 125, ${state === 'ghost' ? 0.55 : 0})`
+    fill: state === 'ghost' ? `rgba(${ground.value.join(', ')}, 0)` : state === 'dim' ? tint(piece.fill, 0.28) : piece.fill,
+    stroke: `rgba(${outline.value.join(', ')}, ${state === 'ghost' ? 0.55 : 0})`
   }
 }
 </script>
diff --git a/.vitepress/theme/home/HomeFacades.vue b/.vitepress/theme/home/HomeFacades.vue
index 3ff832b13..e35d443aa 100644
--- a/.vitepress/theme/home/HomeFacades.vue
+++ b/.vitepress/theme/home/HomeFacades.vue
@@ -56,11 +56,12 @@ const names = Object.keys(FACADES).sort((a, b) => a.localeCompare(b, 'en', { sen
   border-bottom: 1px solid var(--g-line);
 }
 
-.home-cell::after {
+.home-cell::before {
   content: '';
+  display: none;
   position: absolute;
-  right: -3px;
-  bottom: -3px;
+  left: -3px;
+  top: -3px;
   z-index: 1;
   width: 5px;
   height: 5px;
@@ -83,7 +84,7 @@ const names = Object.keys(FACADES).sort((a, b) => a.localeCompare(b, 'en', { sen
   letter-spacing: 0.08em;
   text-transform: uppercase;
   vertical-align: middle;
-  color: var(--g-white);
+  color: var(--g-on-accent);
   background: var(--g-cyan-text);
 }
 
@@ -107,7 +108,7 @@ const names = Object.keys(FACADES).sort((a, b) => a.localeCompare(b, 'en', { sen
   margin-top: auto;
   padding: 14px 0;
   border: 1px solid var(--g-line);
-  background: var(--g-soft);
+  background: var(--g-code);
   font-size: 12.5px;
   line-height: 24px;
   scrollbar-width: thin;
@@ -167,6 +168,19 @@ const names = Object.keys(FACADES).sort((a, b) => a.localeCompare(b, 'en', { sen
   color: var(--g-ink);
 }
 
+@media (min-width: 1400px) {
+  .home-cell:nth-child(3n + 3)::before,
+  .home-cell:nth-child(3n + 4)::before {
+    display: block;
+  }
+}
+
+@media (min-width: 901px) and (max-width: 1399px) {
+  .home-cell:nth-child(2n + 3)::before {
+    display: block;
+  }
+}
+
 @media (max-width: 1399px) {
   .home-cell .home-code {
     font-size: 13.5px;
diff --git a/.vitepress/theme/home/HomeLaravel.vue b/.vitepress/theme/home/HomeLaravel.vue
index 8bbb013cc..1c2ae2fe5 100644
--- a/.vitepress/theme/home/HomeLaravel.vue
+++ b/.vitepress/theme/home/HomeLaravel.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, nextTick, ref, watch } from 'vue'
-import { useElementHover, useTimeoutFn } from '@vueuse/core'
+import { useElementHover, useTemplateRefsList, useTimeoutFn } from '@vueuse/core'
 import { useI18n } from '../i18n'
 import { useTicker } from './useTicker'
 import CodeLines from './CodeLines.vue'
@@ -13,6 +13,7 @@ const DWELL = 3
 const IDLE = 8000
 
 const at = ref(0)
+const tabs = useTemplateRefsList<HTMLButtonElement>()
 const line = ref(0)
 const dwell = ref(0)
 const touring = ref(true)
@@ -23,6 +24,15 @@ const { ticks, root: card } = useTicker(1500)
 const hovered = useElementHover(card)
 const { start: wake } = useTimeoutFn(() => (touring.value = true), IDLE, { immediate: false })
 
+watch(at, async () => {
+  await nextTick()
+  // scroll only the strip; scrollIntoView would also move the page, which fights the tour
+  const tab = tabs.value[at.value]
+  const strip = tab?.parentElement
+  if (!tab || !strip || strip.scrollWidth <= strip.clientWidth) return
+  strip.scrollTo({ left: tab.offsetLeft - (strip.clientWidth - tab.offsetWidth) / 2, behavior: 'smooth' })
+})
+
 watch(ticks, () => {
   dwell.value++
   if (line.value + 1 < concept.value.ties.length) {
@@ -72,6 +82,7 @@ function onTabKey(event: KeyboardEvent) {
           v-for="(c, i) in LARAVEL.concepts"
           :id="`home-tab-${i}`"
           :key="c.name"
+          :ref="tabs.set"
           type="button"
           role="tab"
           class="g-tab"
@@ -209,7 +220,7 @@ function onTabKey(event: KeyboardEvent) {
 }
 
 .home-brand [class*='laravel'] {
-  color: #ff2d20;
+  color: var(--g-laravel);
 }
 
 .home-file .g-code {
@@ -240,9 +251,22 @@ function onTabKey(event: KeyboardEvent) {
   }
 
   .home-feat-show .g-tabs {
+    position: relative;
+    flex-wrap: nowrap;
     justify-content: flex-start;
     gap: 0 18px;
+    overflow-x: auto;
     padding: 0 16px;
+    scrollbar-width: none;
+  }
+
+  .home-feat-show .g-tab {
+    flex-shrink: 0;
+    white-space: nowrap;
+  }
+
+  .home-feat-show .g-tab::after {
+    bottom: 0;
   }
 
   .home-file {
@@ -277,4 +301,15 @@ function onTabKey(event: KeyboardEvent) {
     font-size: 12.5px;
   }
 }
+
+@media (max-width: 600px) {
+  .home-file .g-file-head {
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  .home-brand {
+    white-space: nowrap;
+  }
+}
 </style>
diff --git a/.vitepress/theme/home/HomeLite.vue b/.vitepress/theme/home/HomeLite.vue
index 10bf30c70..93ecbb2f0 100644
--- a/.vitepress/theme/home/HomeLite.vue
+++ b/.vitepress/theme/home/HomeLite.vue
@@ -148,7 +148,7 @@ const pick = (i: number) => {
   margin: 0;
   padding: 10px 0;
   border: 1px solid var(--g-line);
-  background: var(--g-soft);
+  background: var(--g-code);
   list-style: none;
 }
 
diff --git a/.vitepress/theme/home/HomeOpenSource.vue b/.vitepress/theme/home/HomeOpenSource.vue
index cbfcacc95..1ec32d445 100644
--- a/.vitepress/theme/home/HomeOpenSource.vue
+++ b/.vitepress/theme/home/HomeOpenSource.vue
@@ -511,8 +511,14 @@ const onFocusOut = useDismiss(joins, () => (qr.value = null))
     content: none;
   }
 
-  .os-row.is-join .os-cell:nth-child(n + 3) {
-    border-top: 1px solid var(--g-line);
+  .os-row.is-join .os-cell:nth-child(3)::after {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: calc(var(--g-bleed-left) * -1);
+    right: calc(-100% - var(--g-bleed-right));
+    height: 1px;
+    background: var(--g-line);
   }
 
 
diff --git a/.vitepress/theme/home/home.css b/.vitepress/theme/home/home.css
index 49b9cb697..1dab0d450 100644
--- a/.vitepress/theme/home/home.css
+++ b/.vitepress/theme/home/home.css
@@ -6,7 +6,7 @@
   --g-bleed-left: var(--g-margin);
   --g-bleed-right: var(--g-margin);
   --g-secpad: 56px;
-  --g-grey: #5b6770;
+  --g-grey: var(--g-grey-strong);
   color: var(--g-ink);
   background: var(--g-white);
 }
@@ -128,7 +128,7 @@
   font-size: 16px;
   font-weight: 600;
   white-space: nowrap;
-  color: var(--g-white);
+  color: var(--g-on-accent);
   transition: background-color 0.18s ease, border-color 0.18s ease, color 0.18s ease;
 }
 
diff --git a/.vitepress/theme/i18n.ts b/.vitepress/theme/i18n.ts
index 173fb6ee5..69d46d099 100644
--- a/.vitepress/theme/i18n.ts
+++ b/.vitepress/theme/i18n.ts
@@ -17,6 +17,7 @@ const zh_CN: Dict = {
   Scheduling: '调度',
   Cache: '缓存',
   Testing: '测试',
+  'Switch theme': '切换主题',
   'HTTP layer': 'HTTP 层',
   'Application layer': '应用层',
   'Core layer': '核心层',
@@ -58,9 +59,6 @@ const zh_CN: Dict = {
   'Try these': '试试这些',
   'Upgrading To v1.18 From v1.17': '从 v1.17 升级到 v1.18',
   'Excellent Packages': '优秀扩展包',
-  Methods: '方法',
-  Filter: '筛选',
-  'Filter methods': '筛选方法',
   'Familiar facades, familiar method names': '熟悉的门面，熟悉的方法名',
   'The same file layout, artisan included': '相同的目录结构，自带 artisan',
   'Laravel, line for line.': '与 Laravel 逐行对应。',
diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts
index 98646db3b..51ae30e60 100644
--- a/.vitepress/theme/index.ts
+++ b/.vitepress/theme/index.ts
@@ -45,8 +45,8 @@ export default {
         reactionsEnabled: '1',
         lazyLoad: '1',
         homePageShowComment: '0',
-        lightTheme: 'preferred_color_scheme',
-        darkTheme: 'preferred_color_scheme'
+        lightTheme: 'light',
+        darkTheme: 'transparent_dark'
       },
       {
         frontmatter,
diff --git a/.vitepress/theme/shell.css b/.vitepress/theme/shell.css
index 274c5055c..782dbedb8 100644
--- a/.vitepress/theme/shell.css
+++ b/.vitepress/theme/shell.css
@@ -243,14 +243,39 @@
     padding: 0 !important;
   }
 
+  .VPDoc .aside-container,
   .VPDoc .aside-content {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .VPDoc .aside-content {
+    flex: 1 1 auto;
+    min-height: 0;
+    padding-bottom: 0;
+  }
+
+  .VPDoc .VPDocAside {
+    min-height: 0;
+  }
+
+  .VPDoc .VPDocAsideOutline.has-outline,
+  .VPDoc .VPDocAsideOutline .content {
+    display: flex;
+    flex-direction: column;
     min-height: 0;
-    padding-bottom: 24px;
+  }
+
+  .VPDoc .VPDocAsideOutline .content > .VPDocOutlineItem {
+    min-height: 0;
+    overflow-y: auto;
+    scrollbar-width: thin;
+    scrollbar-color: var(--g-line) transparent;
   }
 }
 
 .VPDocAsideOutline {
-  margin-bottom: 36px;
+  margin-bottom: 0;
   padding: 0 var(--g-shell-inset) 0 var(--g-rail) !important;
   border: 0 !important;
 }
@@ -264,9 +289,7 @@
   display: none;
 }
 
-/* the method index's heading is drawn the same way */
-.VPDocAsideOutline .outline-title,
-.goravel-methods .outline-title {
+.VPDocAsideOutline .outline-title {
   display: flex;
   align-items: center;
   gap: 8px;
@@ -275,8 +298,7 @@
   border-bottom: 1px solid var(--g-line);
 }
 
-.VPDocAsideOutline .outline-title::before,
-.goravel-methods .outline-title::before {
+.VPDocAsideOutline .outline-title::before {
   background: var(--g-construct);
 }
 
@@ -299,7 +321,7 @@
 
 .VPDocOutlineItem .outline-link.active::before {
   position: absolute;
-  left: 0;
+  left: 2px;
   top: 11px;
   background: var(--g-cyan);
 }
@@ -320,6 +342,10 @@
   .VPLocalNav {
     padding-left: calc(var(--vp-sidebar-width) + var(--g-gutter)) !important;
   }
+
+  .VPLocalNavOutlineDropdown {
+    padding-left: 0 !important;
+  }
 }
 
 .VPLocalNav .menu,
@@ -331,15 +357,15 @@
 .VPLocalNavOutlineDropdown .items {
   border: 1px solid var(--g-line) !important;
   border-radius: 2px !important;
-  box-shadow: 0 10px 28px rgba(16, 24, 32, 0.1) !important;
+  box-shadow: 0 10px 28px rgba(var(--g-shadow), 0.1) !important;
 }
 
 /* ------------------------------------------------------------------ search */
 /* the theme resets Algolia's variables on every DocSearch node, so they are set at that level */
 :root [class*='DocSearch'] {
-  --docsearch-container-background: rgba(16, 24, 32, 0.32);
+  --docsearch-container-background: var(--g-scrim);
   --docsearch-modal-background: var(--g-white);
-  --docsearch-modal-shadow: 0 16px 48px rgba(16, 24, 32, 0.12);
+  --docsearch-modal-shadow: 0 16px 48px rgba(var(--g-shadow), 0.12);
   --docsearch-searchbox-shadow: none;
   --docsearch-searchbox-focus-background: var(--g-white);
   --docsearch-highlight-color: var(--g-cyan-text);
diff --git a/.vitepress/theme/styles.css b/.vitepress/theme/styles.css
index e217c686f..9a77976e7 100644
--- a/.vitepress/theme/styles.css
+++ b/.vitepress/theme/styles.css
@@ -2,3 +2,5 @@
 /* icons as classes, such as icon-[simple-icons--discord], from the installed Iconify sets */
 @plugin '@iconify/tailwind4';
 @source '../config';
+/* VitePress names the outline dropdown's list `outline`, which Tailwind would otherwise style as its utility */
+@source not inline('outline');
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..196eb31e7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,11 @@
+# Goravel docs
+
+This repository is the documentation site for Goravel, built with VitePress. Pages live in `en/` and `zh_CN/`. The theme lives in `.vitepress/theme/`.
+
+Before you write or edit a page, read [en/prologue/writing-docs.md](en/prologue/writing-docs.md) and follow it. It is the only writing guide, and it wins over anything you assume about Markdown or VitePress.
+
+The theme has one rule of its own:
+
+- Never write a color in the theme or in a page. Use the `--g-*` tokens in `.vitepress/theme/goravel.css`, so the light and dark themes both work.
+
+Verify with `pnpm docs:build`, which fails on dead links. Preview with `pnpm docs:dev`.
diff --git a/README.md b/README.md
index fbf4c4981..71afcb39e 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,14 @@ This is goravel official document.
 
 ## Contributing
 
-We welcome contributions to the Goravel documentation. Please see the [contributing guide](en/prologue/contributions.md) for more information.
+We welcome contributions to the Goravel documentation. The guide to writing a page is a page in the docs themselves, so it can show every feature of the theme as it renders:
+
+- Read it rendered: https://www.goravel.dev/prologue/writing-docs.html
+- Read or edit its source: [en/prologue/writing-docs.md](en/prologue/writing-docs.md)
+
+The page is not listed in the sidebar or in search, because it is for writers, not for readers of the docs. `pnpm docs:build` fails on dead links, so run it before every PR.
+
+For contributing to Goravel in general, see the [contribution guide](en/prologue/contributions.md).
 
 ## Install
 
diff --git a/en/prologue/compare-with-laravel.md b/en/prologue/compare-with-laravel.md
index 946d52eba..3ef75fd86 100644
--- a/en/prologue/compare-with-laravel.md
+++ b/en/prologue/compare-with-laravel.md
@@ -39,6 +39,7 @@ Goravel follows the structure of Laravel, so the concepts, the facades and most
 | [Validation](../the-basics/validation.md) | `$request->validate([...])` | `ctx.Request().ValidateRequest(&storePost)` |
 | [View](../the-basics/views.md) | `view('welcome')` | `ctx.Response().View().Make("welcome.tmpl")` |
 | [Grpc](../the-basics/grpc.md) | <Brand laravel no /> Not built in | `facades.Grpc().Connect("user")` |
+| [Telemetry](../digging-deeper/telemetry.md) | <Brand laravel no /> Not built in | `facades.Telemetry().Tracer("app").Start(ctx, "order.process")` |
 | Notifications | `$user->notify(new InvoicePaid())` | <Brand goravel no /> Not yet |
 | Broadcasting | `broadcast(new OrderShipped($order))` | <Brand goravel no /> Not yet |
 | Livewire | `<livewire:counter />` | <Brand goravel no /> Not yet |
diff --git a/en/prologue/writing-docs.md b/en/prologue/writing-docs.md
new file mode 100644
index 000000000..23be2f4c0
--- /dev/null
+++ b/en/prologue/writing-docs.md
@@ -0,0 +1,251 @@
+---
+head:
+  - - meta
+    - name: robots
+      content: noindex
+---
+
+# Writing Documentation
+
+## Introduction
+
+This page is for people and AI agents who write or edit these docs. It explains how to write a page a developer can follow without getting stuck, and it shows every feature of the docs theme as you write it and as it renders.
+
+Every example on this page is written once: the block shows its source, and the result under it is rendered from that same source.
+
+Preview your changes with `pnpm docs:dev`, and run `pnpm docs:build` before opening a PR. The build fails on dead links.
+
+## What A Good Page Does
+
+The reader has a task and wants to get back to their code. A good page gets them there.
+
+- **It answers "how do I do X".** Organize a page by what the reader wants to do, not by how the package is built inside.
+- **It can be pasted.** Every example runs when it is copied into a fresh project.
+- **It can be scanned.** The outline on the right lists every `##` and `###` heading, so the reader finds the section without reading from the top.
+- **It is true.** Every method, option and config key exists in the framework today.
+- **It feels familiar.** Goravel follows Laravel. Use the names a Laravel developer already knows, and say where Goravel differs.
+
+Order the sections the way a reader meets them: introduction, installation or configuration, the common tasks, the rarer tasks, extending, testing.
+
+## Writing A Section
+
+One section covers one task. Write it in this order.
+
+1. **A heading that names the task.** "Storing Items For A Limited Time", not "Put". The reader searches for what they want to do. Reference pages with one short section per method are the exception, and there the method is the heading.
+2. **One sentence that names the method** in inline code. It tells the reader what to look for in the example.
+3. **A complete example** that starts with its file path.
+4. **What comes back, and what can go wrong**, when the reader could be surprised.
+5. **A callout, only when needed.** One gotcha that would cost the reader an hour belongs in a warning. Most sections need none.
+
+Keep a section short. When a section needs more than two examples, it is two tasks.
+
+````md demo
+### Storing Items For A Limited Time
+
+You may use the `Put` method to store an item for a given time:
+
+```go
+// app/http/controllers/user_controller.go
+package controllers
+
+import (
+	"time"
+
+	"github.com/goravel/framework/contracts/http"
+
+	"goravel/app/facades"
+)
+
+func (r *UserController) Show(ctx http.Context) http.Response {
+	err := facades.Cache().Put("user", "Goravel", 5*time.Minute)
+	if err != nil {
+		return ctx.Response().Status(500).String(err.Error())
+	}
+
+	return ctx.Response().Success().String("cached")
+}
+```
+
+::: warning Zero means forever
+A duration of `0` stores the item with no expiry.
+:::
+````
+
+## Writing Examples
+
+Examples are the part of the docs people actually use.
+
+- **Make it complete.** Start the block with the file path as a comment, then the package, the imports and the function around the call. A fragment of one to three lines is only right when the text around it already shows where it goes, such as a single config line.
+- **Check it against the framework.** Open the contract in `goravel/framework` and confirm the method name, the arguments and the return values. An example that calls a method that does not exist is worse than no example.
+- **Handle the error.** Show `if err != nil` the way real code would, not `_`.
+- **Use real names.** `user`, `order`, `invoice`. Not `foo`, `bar` or `test`.
+- **Show the result** when it is not obvious, as a comment on the last line or in a `text` block under the example.
+- **Write artisan commands as `go run . artisan`.** The `./artisan` script does not run on Windows.
+- **Shell comments start with `#`.** The copy button copies the whole block, and a `//` line makes the command fail.
+- **One idea per block.** Two alternatives go in a code group, not in one long block with comments between them.
+- **Always name the language.** A block without one has no highlighting. Use `go`, `shell`, `json`, `yaml`, `sql`, `dockerfile`, `html`, `php`, `diff`, or `text` for directory trees and plain output.
+
+## Callouts
+
+Use a callout for what the reader must not miss. Never write `Note:`, `Tip:` or `Warning:` as plain text.
+
+| You want to | Use |
+| ----------- | --- |
+| Help the reader do it better | `::: tip` |
+| Add background the reader can skip | `::: info` |
+| Stop a surprise | `::: warning` |
+| Stop a loss of data or a production failure | `::: danger` |
+| Keep a long config out of the way | `::: details Title` |
+
+````md demo
+::: tip
+A shortcut, or a better way to do what the reader is already doing.
+:::
+
+::: info
+Background the reader can skip.
+:::
+
+::: warning Zero values are skipped
+Words after the type become the title.
+:::
+
+::: danger
+Something that loses data or breaks production.
+:::
+
+::: details Show the full config
+Folded until the reader opens it.
+:::
+````
+
+## Code Blocks
+
+### File name header
+
+When the first line is only a comment holding a file path, it becomes the title of the block. It works with `//`, `#` and `--` comments. A block that uses line highlights keeps the comment as a line.
+
+````md demo
+```go
+// config/cache.go
+"default": "memory",
+```
+````
+
+### Line and word highlights
+
+````md demo
+```go{2}
+func Boot() {
+	facades.Route().Run()
+}
+```
+
+```go /taskController/
+facades.Route().Get("/tasks", taskController.Index)
+```
+````
+
+### Changes, warnings and errors
+
+Put the mark in a comment at the end of the line. `// [!code focus]` blurs every other line until the reader hovers the block. For a whole-file before and after, use the `diff` language.
+
+````md demo
+```go
+facades.Log().Debug("removed") // [!code --]
+facades.Log().Info("added")    // [!code ++]
+facades.Log().Warn("careful")  // [!code warning]
+facades.Log().Error("bad")     // [!code error]
+```
+````
+
+### Code groups
+
+Use a group when the same step has more than one form, such as two drivers or two operating systems. The label becomes the tab, and a file name or known tool gets its icon.
+
+````md demo
+::: code-group
+
+```go [main.go]
+package main
+
+func main() {}
+```
+
+```shell [run]
+go run .
+```
+
+:::
+````
+
+### Demos
+
+A fence opened as ````md demo` shows its source and then renders it. It exists for pages like this one that teach Markdown itself, so an example is written once. A page about Goravel never needs it.
+
+### One-line commands
+
+Line numbers are on everywhere. Turn them off for a one-line command.
+
+````md demo
+```shell:no-line-numbers
+go run . artisan key:generate
+```
+````
+
+## Tables And Inline Elements
+
+Keep the first column of a table short, because it never breaks in the middle of a name. A page with a very wide table can hide the outline with `aside: false` in its frontmatter.
+
+````md demo
+| Facade | Purpose | Since |
+| ------ | ------- | ----- |
+| `AI` | Agents and tools | <Badge type="tip" text="v1.18" /> |
+| `Telemetry` | Traces, metrics and logs | <Badge type="tip" text="v1.18" /> |
+
+Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to open search.
+
+- [x] A finished step
+- [ ] An open step
+
+| Feature | Laravel | Goravel |
+| ------- | ------- | ------- |
+| Grpc | <Brand laravel no /> Not built in | <Brand goravel /> `facades.Grpc()` |
+````
+
+A badge takes the type `info`, `tip`, `warning` or `danger`.
+
+## Words
+
+- Write to the reader as "you", in the present tense: "The `Get` method returns the item."
+- Keep sentences short. One idea each.
+- Drop "simply", "just", "easily" and "obviously". If it were obvious, the reader would not be here.
+- Use one word for one thing across the page. Do not switch between "driver", "store" and "adapter" for the same thing.
+- Put names of methods, files, config keys, commands and values in inline code.
+- Do not write numbers that go stale, such as how many facades, drivers or stars there are.
+- Say what a thing does, not how good it is: "runs up to ten processes at once", not "a powerful concurrency engine".
+
+## Two Languages
+
+- Every page exists in `en/` and `zh_CN/` with the same headings in the same order and the same code blocks. Change both in the same PR.
+- Translate the text. Keep code, method names, file paths and config keys as they are.
+- Link to a page with a relative path to the `.md` file, such as `../architecture-concepts/facades.md#install-uninstall-facades`.
+- An anchor is the heading in lower case with hyphens for spaces. A Chinese page has Chinese anchors, so never copy an English anchor into a Chinese page. Give a heading a fixed anchor when it may be renamed: `### Update columns {#update-columns}`.
+- A new page goes into the sidebar in both `.vitepress/config/en.ts` and `.vitepress/config/zh_CN.ts`.
+
+## Light And Dark
+
+Switch the theme with the button in the top bar and check your page in both.
+
+- Never write a color in a page. Raw HTML uses the theme tokens: `var(--g-ink)` for text, `var(--g-grey)` for quiet text, `var(--g-line)` for rules, `var(--g-cyan)` for the accent, `var(--g-code)` for a code ground.
+- Use images with a transparent background that stay readable on a dark ground, or give them their own solid ground.
+
+## Before You Open A PR
+
+- [ ] `pnpm docs:build` passes
+- [ ] Each section names its task in the heading and its method in the first sentence
+- [ ] Every example is complete, starts with its file path, and uses methods that exist in the framework
+- [ ] Every code block has a language, and shell comments use `#`
+- [ ] The outline reads as a list of tasks, because every `##` and `###` heading is in it
+- [ ] English and Chinese have the same headings and code blocks, and Chinese pages use Chinese anchors
+- [ ] You looked at the page in both the light and the dark theme
diff --git a/zh_CN/prologue/compare-with-laravel.md b/zh_CN/prologue/compare-with-laravel.md
index d2d20137d..0e35932e1 100644
--- a/zh_CN/prologue/compare-with-laravel.md
+++ b/zh_CN/prologue/compare-with-laravel.md
@@ -39,6 +39,7 @@ Goravel 沿用了 Laravel 的结构，因此概念、门面以及大部分方法
 | [表单验证](../the-basics/validation.md) | `$request->validate([...])` | `ctx.Request().ValidateRequest(&storePost)` |
 | [视图](../the-basics/views.md) | `view('welcome')` | `ctx.Response().View().Make("welcome.tmpl")` |
 | [Grpc](../the-basics/grpc.md) | <Brand laravel no /> 未内置 | `facades.Grpc().Connect("user")` |
+| [Telemetry](../digging-deeper/telemetry.md) | <Brand laravel no /> 未内置 | `facades.Telemetry().Tracer("app").Start(ctx, "order.process")` |
 | 通知 | `$user->notify(new InvoicePaid())` | <Brand goravel no /> 暂未支持 |
 | 广播 | `broadcast(new OrderShipped($order))` | <Brand goravel no /> 暂未支持 |
 | Livewire | `<livewire:counter />` | <Brand goravel no /> 暂未支持 |
diff --git a/zh_CN/prologue/writing-docs.md b/zh_CN/prologue/writing-docs.md
new file mode 100644
index 000000000..04355189b
--- /dev/null
+++ b/zh_CN/prologue/writing-docs.md
@@ -0,0 +1,251 @@
+---
+head:
+  - - meta
+    - name: robots
+      content: noindex
+---
+
+# 编写文档
+
+## 简介
+
+本页面向编写或修改文档的贡献者和 AI 代理，说明如何写出开发者能够顺利跟着做的页面，并展示文档主题的每项功能：怎么写，以及渲染出来的效果。
+
+本页的每个示例都只写了一次：代码块显示源码，下方的效果由同一份源码渲染而来。
+
+使用 `pnpm docs:dev` 预览修改，提交 PR 前运行 `pnpm docs:build`。 存在失效链接时构建会失败。
+
+## 好页面的标准
+
+读者带着任务而来，希望尽快回到自己的代码中。 好的页面能帮他们做到这一点。
+
+- **回答“我该如何做 X”。** 按读者想做的事情组织页面，而不是按包的内部结构组织。
+- **可以直接粘贴。** 每个示例复制到新项目中都能运行。
+- **便于浏览。** 右侧大纲会列出每个 `##` 和 `###` 标题，读者不必从头读起就能找到章节。
+- **内容真实。** 每个方法、选项和配置项在当前框架中都真实存在。
+- **令人熟悉。** Goravel 遵循 Laravel 的风格。 使用 Laravel 开发者熟悉的名称，并说明 Goravel 的不同之处。
+
+按读者接触的顺序排列章节：简介、安装或配置、常见任务、较少见的任务、扩展、测试。
+
+## 编写章节
+
+一个章节只讲一个任务，请按以下顺序编写。
+
+1. **用标题说明任务。** 写“在限定时间内存储数据”，而不是“Put”。 读者搜索的是他们想做的事。 每个方法一小节的参考类页面是例外，此时标题就是方法名。
+2. **用一句话写出方法名**，并使用行内代码。 它告诉读者在示例中关注什么。
+3. **一个完整的示例**，以文件路径开头。
+4. **返回什么，可能出什么错**，当读者可能感到意外时说明。
+5. **只在需要时使用提示块。** 一个可能让读者耗费一小时的坑，应该放进 warning。 大多数章节不需要提示块。
+
+保持章节简短。 如果一个章节需要两个以上的示例，它其实是两个任务。
+
+````md demo
+### 在限定时间内存储数据
+
+你可以使用 `Put` 方法在指定时间内存储数据：
+
+```go
+// app/http/controllers/user_controller.go
+package controllers
+
+import (
+	"time"
+
+	"github.com/goravel/framework/contracts/http"
+
+	"goravel/app/facades"
+)
+
+func (r *UserController) Show(ctx http.Context) http.Response {
+	err := facades.Cache().Put("user", "Goravel", 5*time.Minute)
+	if err != nil {
+		return ctx.Response().Status(500).String(err.Error())
+	}
+
+	return ctx.Response().Success().String("cached")
+}
+```
+
+::: warning 零表示永久
+时长为 `0` 时，数据将永不过期。
+:::
+````
+
+## 编写示例
+
+示例是文档中人们真正会用到的部分。
+
+- **保持完整。** 代码块以文件路径注释开头，然后是包名、导入以及调用所在的函数。 只有当上下文已经说明代码位置时，才适合只写一到三行的片段，例如单行配置。
+- **对照框架进行核对。** 打开 `goravel/framework` 中的契约，确认方法名、参数和返回值。 调用了不存在的方法的示例，比没有示例更糟糕。
+- **处理错误。** 像真实代码那样写出 `if err != nil`，而不是用 `_` 忽略。
+- **使用真实的名称。** 使用 `user`、`order`、`invoice`，不要用 `foo`、`bar` 或 `test`。
+- **展示结果**，当结果不明显时，写在最后一行的注释中，或写在示例下方的 `text` 代码块中。
+- **artisan 命令写作 `go run . artisan`。** `./artisan` 脚本无法在 Windows 上运行。
+- **Shell 注释以 `#` 开头。** 复制按钮会复制整个代码块，`//` 开头的行会导致命令执行失败。
+- **一个代码块只表达一件事。** 两种替代写法请放进代码组，不要写成一个中间夹着注释的长代码块。
+- **始终标明语言。** 没有标明语言的代码块不会高亮。 可使用 `go`、`shell`、`json`、`yaml`、`sql`、`dockerfile`、`html`、`php`、`diff`，目录树和纯文本输出使用 `text`。
+
+## 提示块
+
+需要读者特别留意的内容请使用提示块。 不要用纯文本写 `注意：`、`提示：` 或 `警告：`。
+
+| 你想要 | 使用 |
+| ------ | ---- |
+| 帮助读者做得更好 | `::: tip` |
+| 补充读者可以跳过的背景 | `::: info` |
+| 避免读者感到意外 | `::: warning` |
+| 避免数据丢失或生产环境故障 | `::: danger` |
+| 把很长的配置收起来 | `::: details 标题` |
+
+````md demo
+::: tip
+一个捷径，或者读者正在做的事情的更好做法。
+:::
+
+::: info
+读者可以跳过的背景信息。
+:::
+
+::: warning 零值会被忽略
+类型后面的文字会成为标题。
+:::
+
+::: danger
+会导致数据丢失或生产环境故障的内容。
+:::
+
+::: details 查看完整配置
+折叠的内容，读者需要时再展开。
+:::
+````
+
+## 代码块
+
+### 文件名标题
+
+当第一行只是一条包含文件路径的注释时，它会成为代码块的标题。 `//`、`#` 和 `--` 注释都适用。 使用了行高亮的代码块会保留这行注释。
+
+````md demo
+```go
+// config/cache.go
+"default": "memory",
+```
+````
+
+### 行高亮和单词高亮
+
+````md demo
+```go{2}
+func Boot() {
+	facades.Route().Run()
+}
+```
+
+```go /taskController/
+facades.Route().Get("/tasks", taskController.Index)
+```
+````
+
+### 变更、警告和错误
+
+在行尾的注释中写入标记。 `// [!code focus]` 会模糊其他所有行，直到读者将鼠标悬停在代码块上。 如需展示整个文件修改前后的对比，请使用 `diff` 语言。
+
+````md demo
+```go
+facades.Log().Debug("removed") // [!code --]
+facades.Log().Info("added")    // [!code ++]
+facades.Log().Warn("careful")  // [!code warning]
+facades.Log().Error("bad")     // [!code error]
+```
+````
+
+### 代码组
+
+同一步骤有多种形式时使用代码组，例如两种驱动或两种操作系统。 标签会成为选项卡，文件名或常见工具名会自动显示图标。
+
+````md demo
+::: code-group
+
+```go [main.go]
+package main
+
+func main() {}
+```
+
+```shell [run]
+go run .
+```
+
+:::
+````
+
+### 演示块
+
+以 ````md demo` 开头的代码块会先显示源码，再把它渲染出来。 它只用于像本页这样讲解 Markdown 本身的页面，让示例只写一次。 介绍 Goravel 的页面不需要它。
+
+### 单行命令
+
+所有代码块默认显示行号。 单行命令可以关闭行号。
+
+````md demo
+```shell:no-line-numbers
+go run . artisan key:generate
+```
+````
+
+## 表格和行内元素
+
+表格的第一列请保持简短，因为它不会在名称中间换行。 包含超宽表格的页面可以在 frontmatter 中使用 `aside: false` 隐藏大纲。
+
+````md demo
+| Facade | 用途 | 起始版本 |
+| ------ | ---- | -------- |
+| `AI` | 代理和工具 | <Badge type="tip" text="v1.18" /> |
+| `Telemetry` | 追踪、指标和日志 | <Badge type="tip" text="v1.18" /> |
+
+按 <kbd>Ctrl</kbd> + <kbd>K</kbd> 打开搜索。
+
+- [x] 已完成的步骤
+- [ ] 未完成的步骤
+
+| 功能 | Laravel | Goravel |
+| ---- | ------- | ------- |
+| Grpc | <Brand laravel no /> 未内置 | <Brand goravel /> `facades.Grpc()` |
+````
+
+徽章的类型可以是 `info`、`tip`、`warning` 或 `danger`。
+
+## 用词
+
+- 用“你”称呼读者，使用现在时：“`Get` 方法返回该数据。”
+- 句子保持简短，一句话只表达一个意思。
+- 去掉“只需”“简单地”“轻松地”和“显然”。 如果真的显而易见，读者就不会来看文档了。
+- 同一页面中，一个事物只用一个词。 不要对同一个东西交替使用“驱动”“存储”和“适配器”。
+- 方法、文件、配置项、命令和值的名称使用行内代码。
+- 不要写会过时的数字，例如有多少个 facades、驱动或 star。
+- 说明它做什么，而不是它有多好：写“最多同时运行十个进程”，不要写“强大的并发引擎”。
+
+## 两种语言
+
+- 每个页面在 `en/` 和 `zh_CN/` 中都存在，标题及其顺序、代码块保持一致。 请在同一个 PR 中修改两种语言。
+- 翻译正文。 代码、方法名、文件路径和配置项保持原样。
+- 使用指向 `.md` 文件的相对路径链接页面，例如 `../architecture-concepts/facades.md#安装-卸载-facades`。
+- 锚点是标题转为小写、空格替换为连字符后的结果。 中文页面使用中文锚点，不要把英文锚点复制到中文页面。 如果标题以后可能改名，请为它指定固定的锚点：`### 更新字段 {#update-columns}`。
+- 新页面需要同时加入 `.vitepress/config/en.ts` 和 `.vitepress/config/zh_CN.ts` 的侧边栏。
+
+## 浅色与深色
+
+使用顶部栏的按钮切换主题，并在两种主题下检查你的页面。
+
+- 不要在页面中直接写颜色值。 原始 HTML 请使用主题变量：文字用 `var(--g-ink)`，次要文字用 `var(--g-grey)`，分隔线用 `var(--g-line)`，强调色用 `var(--g-cyan)`，代码背景用 `var(--g-code)`。
+- 图片请使用透明背景，并确保在深色背景上依然清晰，或者为图片提供自己的纯色背景。
+
+## 提交 PR 之前
+
+- [ ] `pnpm docs:build` 构建通过
+- [ ] 每个章节的标题说明了任务，第一句话写出了方法名
+- [ ] 每个示例都完整，以文件路径开头，并且使用框架中真实存在的方法
+- [ ] 每个代码块都标明了语言，shell 注释使用 `#`
+- [ ] 大纲读起来是一份任务列表，因为每个 `##` 和 `###` 标题都会出现在其中
+- [ ] 中英文页面的标题和代码块一致，中文页面使用中文锚点
+- [ ] 你已在浅色和深色两种主题下查看过页面