From 09433415b63c7510b6e7819d9c2dd94d1531b65e Mon Sep 17 00:00:00 2001
From: robonen <robonenandrew@gmail.com>
Date: Mon, 8 Jun 2026 15:52:03 +0700
Subject: [PATCH] feat(docs): doc-sections system, crdt package, MCP server,
 and responsive fixes

Adds a hand-authored .vue doc-sections system (intro + guide pages per package, #docs/sections map, sidebar Guide group, client-side TOC), registers @robonen/crdt, renders demos client-only, base64-encodes the server-metadata virtual, plus the MCP docs endpoint and responsive/overflow fixes across pages and tables.
---
 docs/app/components/DocsDemo.vue        |  20 +-
 docs/app/components/DocsEmitsTable.vue  |   2 +-
 docs/app/components/DocsParamsTable.vue |   2 +-
 docs/app/components/DocsPropsTable.vue  |   2 +-
 docs/app/composables/useDocs.ts         |  20 +-
 docs/app/composables/useMarkdown.ts     |  14 +-
 docs/app/layouts/default.vue            |  35 ++-
 docs/app/pages/[package]/[utility].vue  |  47 +++-
 docs/app/pages/[package]/index.vue      |  32 ++-
 docs/app/pages/index.vue                |   2 +-
 docs/modules/extractor/extract.ts       |  72 ++++++-
 docs/modules/extractor/index.ts         |  70 +++++-
 docs/modules/extractor/types.ts         |  23 ++
 docs/modules/mcp/README.md              |  65 ++++++
 docs/modules/mcp/create-server.ts       | 160 ++++++++++++++
 docs/modules/mcp/docs-index.test.ts     | 232 ++++++++++++++++++++
 docs/modules/mcp/docs-index.ts          | Bin 0 -> 9517 bytes
 docs/modules/mcp/format.ts              | 274 ++++++++++++++++++++++++
 docs/nuxt.config.ts                     |  10 +
 docs/package.json                       |   4 +-
 docs/server/routes/mcp.post.ts          |  39 ++++
 docs/server/types.d.ts                  |   7 +
 docs/vitest.config.ts                   |  10 +
 23 files changed, 1107 insertions(+), 35 deletions(-)
 create mode 100644 docs/modules/mcp/README.md
 create mode 100644 docs/modules/mcp/create-server.ts
 create mode 100644 docs/modules/mcp/docs-index.test.ts
 create mode 100644 docs/modules/mcp/docs-index.ts
 create mode 100644 docs/modules/mcp/format.ts
 create mode 100644 docs/server/routes/mcp.post.ts
 create mode 100644 docs/server/types.d.ts
 create mode 100644 docs/vitest.config.ts

diff --git a/docs/app/components/DocsDemo.vue b/docs/app/components/DocsDemo.vue
index e81d5b3..8e1962c 100644
--- a/docs/app/components/DocsDemo.vue
+++ b/docs/app/components/DocsDemo.vue
@@ -1,4 +1,5 @@
-<script setup lang="ts">import type { Component } from 'vue';
+<script setup lang="ts">
+import type { Component } from 'vue';
 
 const props = defineProps<{
   component: Component;
@@ -18,9 +19,20 @@ watch(showSource, async (show) => {
 
 <template>
   <div class="rounded-xl border border-(--border) overflow-hidden">
-    <!-- Live demo -->
-    <div class="p-8 bg-(--bg-subtle) flex items-center justify-center min-h-32">
-      <component :is="component" />
+    <!-- Live demo — client-only: demos are interactive and use browser APIs,
+         so they must not be instantiated during SSR/prerender. -->
+    <div class="p-4 sm:p-8 bg-(--bg-subtle) flex items-center justify-center min-h-32">
+      <ClientOnly>
+        <component :is="component" />
+        <template #fallback>
+          <div class="flex items-center gap-2 text-sm text-(--fg-subtle)">
+            <svg class="animate-spin" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+            </svg>
+            Loading demo…
+          </div>
+        </template>
+      </ClientOnly>
     </div>
 
     <!-- Source toggle bar -->
diff --git a/docs/app/components/DocsEmitsTable.vue b/docs/app/components/DocsEmitsTable.vue
index 37119b1..c0c95b8 100644
--- a/docs/app/components/DocsEmitsTable.vue
+++ b/docs/app/components/DocsEmitsTable.vue
@@ -6,7 +6,7 @@ defineProps<{
 </script>
 
 <template>
-  <div v-if="emits.length > 0" class="overflow-hidden rounded-xl border border-(--border)">
+  <div v-if="emits.length > 0" class="overflow-x-auto rounded-xl border border-(--border)">
     <table class="w-full text-sm border-collapse">
       <thead>
         <tr class="bg-(--bg-subtle) text-left">
diff --git a/docs/app/components/DocsParamsTable.vue b/docs/app/components/DocsParamsTable.vue
index 1ac9099..3ddae0a 100644
--- a/docs/app/components/DocsParamsTable.vue
+++ b/docs/app/components/DocsParamsTable.vue
@@ -6,7 +6,7 @@ defineProps<{
 </script>
 
 <template>
-  <div v-if="params.length > 0" class="overflow-hidden rounded-xl border border-(--border)">
+  <div v-if="params.length > 0" class="overflow-x-auto rounded-xl border border-(--border)">
     <table class="w-full text-sm border-collapse">
       <thead>
         <tr class="bg-(--bg-subtle) text-left">
diff --git a/docs/app/components/DocsPropsTable.vue b/docs/app/components/DocsPropsTable.vue
index 0cd4c7e..399e4ee 100644
--- a/docs/app/components/DocsPropsTable.vue
+++ b/docs/app/components/DocsPropsTable.vue
@@ -8,7 +8,7 @@ defineProps<{
 </script>
 
 <template>
-  <div v-if="properties.length > 0" class="overflow-hidden rounded-xl border border-(--border)">
+  <div v-if="properties.length > 0" class="overflow-x-auto rounded-xl border border-(--border)">
     <table class="w-full text-sm border-collapse">
       <thead>
         <tr class="bg-(--bg-subtle) text-left">
diff --git a/docs/app/composables/useDocs.ts b/docs/app/composables/useDocs.ts
index 6a7e348..56d4a55 100644
--- a/docs/app/composables/useDocs.ts
+++ b/docs/app/composables/useDocs.ts
@@ -2,6 +2,7 @@ import metadata from '#docs/metadata';
 import type {
   CategoryMeta,
   ComponentMeta,
+  DocSection,
   DocsMetadata,
   GuideSection,
   ItemMeta,
@@ -13,7 +14,8 @@ import type {
 export type DocEntry
   = | { kind: 'api'; pkg: PackageMeta; category: CategoryMeta; item: ItemMeta }
     | { kind: 'components'; pkg: PackageMeta; component: ComponentMeta }
-    | { kind: 'guide'; pkg: PackageMeta; section: GuideSection };
+    | { kind: 'guide'; pkg: PackageMeta; section: GuideSection }
+    | { kind: 'doc'; pkg: PackageMeta; section: DocSection };
 
 export interface SearchResult {
   pkg: PackageMeta;
@@ -62,11 +64,25 @@ export function useDocs() {
     return pkg.sections.length;
   }
 
+  /** The hand-authored intro section for a package, if any. */
+  function getIntro(pkg: PackageMeta): DocSection | undefined {
+    return pkg.docs.find(s => s.isIntro);
+  }
+
+  /** Non-intro doc sections (the "Guide" list shown in the sidebar). */
+  function getDocSections(pkg: PackageMeta): DocSection[] {
+    return pkg.docs.filter(s => !s.isIntro);
+  }
+
   /** Resolve any `/:package/:slug` route to a normalised entry. */
   function resolveEntry(packageSlug: string, slug: string): DocEntry | undefined {
     const pkg = getPackage(packageSlug);
     if (!pkg) return undefined;
 
+    // Hand-authored doc sections take precedence over auto-generated leaves.
+    const docSection = pkg.docs.find(s => !s.isIntro && s.slug === slug);
+    if (docSection) return { kind: 'doc', pkg, section: docSection };
+
     if (pkg.kind === 'api') {
       for (const category of pkg.categories) {
         const item = category.items.find(i => i.slug === slug);
@@ -139,6 +155,8 @@ export function useDocs() {
     countEntries,
     resolveEntry,
     firstEntrySlug,
+    getIntro,
+    getDocSections,
     search,
     getTotalItems,
   };
diff --git a/docs/app/composables/useMarkdown.ts b/docs/app/composables/useMarkdown.ts
index aa3bf0e..c7ac126 100644
--- a/docs/app/composables/useMarkdown.ts
+++ b/docs/app/composables/useMarkdown.ts
@@ -9,10 +9,10 @@ export interface Heading {
 export function slugHeading(text: string): string {
   return text
     .toLowerCase()
-    .replace(/`/g, '')
-    .replace(/[^\w\s-]/g, '')
+    .replaceAll('`', '')
+    .replaceAll(/[^\w\s-]/g, '')
     .trim()
-    .replace(/\s+/g, '-');
+    .replaceAll(/\s+/g, '-');
 }
 
 /** Collect h2/h3 headings for the table of contents. */
@@ -28,11 +28,13 @@ export function extractHeadings(markdown: string): Heading[] {
     }
     if (inFence) continue;
 
-    const m = line.match(/^(#{2,3})\s+(.+?)\s*#*$/);
+    const m = line.match(/^(#{2,3})\s+(\S.*)$/);
     if (!m) continue;
 
     const depth = m[1]!.length;
-    const text = m[2]!.replace(/`/g, '').trim();
+    // Strip an optional ATX closing run (a single space then trailing `#`s) without
+    // a backtracking-prone pattern, then drop inline code ticks.
+    const text = m[2]!.replace(/ #+ *$/, '').replaceAll('`', '').trim();
     let id = slugHeading(text);
     const count = seen.get(id) ?? 0;
     seen.set(id, count + 1);
@@ -51,7 +53,7 @@ export function renderMarkdown(markdown: string): string {
   const renderer = new marked.Renderer();
   renderer.heading = function ({ tokens, depth }) {
     const inner = this.parser.parseInline(tokens);
-    const plain = inner.replace(/<[^>]+>/g, '');
+    const plain = inner.replaceAll(/<[^>]+>/g, '');
     let id = slugHeading(plain);
     const count = seen.get(id) ?? 0;
     seen.set(id, count + 1);
diff --git a/docs/app/layouts/default.vue b/docs/app/layouts/default.vue
index 34f51b5..0c454ea 100644
--- a/docs/app/layouts/default.vue
+++ b/docs/app/layouts/default.vue
@@ -1,4 +1,4 @@
-<script setup lang="ts">const { getGroupedPackages, getPackage } = useDocs();
+<script setup lang="ts">const { getGroupedPackages, getPackage, getIntro, getDocSections } = useDocs();
 const groups = getGroupedPackages();
 
 const route = useRoute();
@@ -91,6 +91,39 @@ watch(() => route.path, () => {
 
                 <!-- Expanded tree for the current package -->
                 <div v-if="currentPackageSlug === pkg.slug && currentPackage" class="mt-1 mb-2 ml-2 pl-3 border-l border-(--border)">
+                  <!-- Hand-authored guide sections (intro + prose pages) -->
+                  <div v-if="currentPackage.docs.length" class="mb-2">
+                    <div class="text-[11px] font-medium text-(--fg-subtle) py-1 px-1">Guide</div>
+                    <ul>
+                      <li v-if="getIntro(currentPackage)">
+                        <NuxtLink
+                          :to="`/${pkg.slug}`"
+                          :class="[
+                            'block py-1 px-2 text-[13px] rounded-md transition-colors truncate',
+                            route.path === `/${pkg.slug}`
+                              ? 'text-(--accent-text) bg-(--accent-subtle) font-medium'
+                              : 'text-(--fg-muted) hover:text-(--fg) hover:bg-(--bg-inset)',
+                          ]"
+                        >
+                          Introduction
+                        </NuxtLink>
+                      </li>
+                      <li v-for="s in getDocSections(currentPackage)" :key="s.slug">
+                        <NuxtLink
+                          :to="`/${pkg.slug}/${s.slug}`"
+                          :class="[
+                            'block py-1 px-2 text-[13px] rounded-md transition-colors truncate',
+                            isActive(pkg.slug, s.slug)
+                              ? 'text-(--accent-text) bg-(--accent-subtle) font-medium'
+                              : 'text-(--fg-muted) hover:text-(--fg) hover:bg-(--bg-inset)',
+                          ]"
+                        >
+                          {{ s.title }}
+                        </NuxtLink>
+                      </li>
+                    </ul>
+                  </div>
+
                   <!-- api -->
                   <template v-if="currentPackage.kind === 'api'">
                     <div v-for="cat in currentPackage.categories" :key="cat.slug" class="mb-2">
diff --git a/docs/app/pages/[package]/[utility].vue b/docs/app/pages/[package]/[utility].vue
index ac0dfc2..9f724d7 100644
--- a/docs/app/pages/[package]/[utility].vue
+++ b/docs/app/pages/[package]/[utility].vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">import { demos } from '#docs/demos';
+import { sections } from '#docs/sections';
 
 const route = useRoute();
 const { resolveEntry } = useDocs();
@@ -18,6 +19,35 @@ if (!entry.value) {
 const pkg = computed(() => entry.value!.pkg);
 
 const demoComponent = computed(() => demos[`${packageSlug.value}/${utilitySlug.value}`] ?? null);
+const sectionComponent = computed(() => sections[`${packageSlug.value}/${utilitySlug.value}`] ?? null);
+
+// ── Doc sections: client-side TOC built from the rendered headings ───────────
+const docRoot = ref<HTMLElement | null>(null);
+const docToc = ref<Array<{ id: string; text: string; depth: number }>>([]);
+
+function buildDocToc() {
+  const el = docRoot.value;
+  if (!el) return;
+  docToc.value = Array.from(el.querySelectorAll('h2, h3')).map((h) => {
+    if (!h.id) {
+      h.id = (h.textContent ?? '')
+        .toLowerCase().trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '');
+    }
+    return { id: h.id, text: h.textContent ?? '', depth: h.tagName === 'H2' ? 2 : 3 };
+  });
+}
+
+onMounted(() => {
+  const el = docRoot.value;
+  if (!el) return;
+  buildDocToc();
+  // The section is an async component — rebuild once its content mounts.
+  const observer = new MutationObserver(() => buildDocToc());
+  observer.observe(el, { childList: true, subtree: true });
+  onScopeDispose(() => observer.disconnect());
+});
 
 function ghUrl(path: string) {
   return `https://github.com/robonen/tools/blob/master/${path}`;
@@ -28,6 +58,7 @@ const title = computed(() => {
   const e = entry.value!;
   if (e.kind === 'api') return e.item.name;
   if (e.kind === 'components') return e.component.name;
+  if (e.kind === 'doc') return e.section.title;
   return e.section.title;
 });
 
@@ -46,6 +77,9 @@ const toc = computed(() => {
   if (e.kind === 'guide') {
     return extractHeadings(e.section.markdown).map(h => ({ id: h.id, text: h.text, depth: h.depth }));
   }
+  if (e.kind === 'doc') {
+    return docToc.value;
+  }
   if (e.kind === 'components') {
     return e.component.parts.map(p => ({ id: p.name.toLowerCase(), text: p.name, depth: 2 }));
   }
@@ -82,7 +116,7 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
         <header class="mb-8">
           <div class="flex items-center gap-2.5 mb-2 flex-wrap">
             <DocsBadge :kind="entry.item.kind" size="md" />
-            <h1 class="text-2xl font-bold font-mono tracking-tight text-(--fg)">{{ entry.item.name }}</h1>
+            <h1 class="min-w-0 break-words text-2xl font-bold font-mono tracking-tight text-(--fg)">{{ entry.item.name }}</h1>
             <DocsTag v-if="entry.item.since" :label="`v${entry.item.since}`" variant="neutral" />
             <DocsTag v-if="entry.item.hasTests" label="tested" variant="test" />
             <DocsTag v-if="entry.item.hasDemo" label="demo" variant="demo" />
@@ -194,10 +228,17 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
         <DocsComponentAnatomy :component="entry.component" :package-name="pkg.name" />
       </template>
 
-      <!-- ── GUIDE ──────────────────────────────────────────────────────── -->
-      <template v-else>
+      <!-- ── GUIDE (Markdown) ───────────────────────────────────────────── -->
+      <template v-else-if="entry.kind === 'guide'">
         <DocsMarkdown :source="entry.section.markdown" />
       </template>
+
+      <!-- ── DOC SECTION (hand-authored .vue) ───────────────────────────── -->
+      <template v-else-if="entry.kind === 'doc'">
+        <div ref="docRoot" class="docs-section">
+          <component :is="sectionComponent" />
+        </div>
+      </template>
     </article>
 
     <!-- Right rail TOC -->
diff --git a/docs/app/pages/[package]/index.vue b/docs/app/pages/[package]/index.vue
index 71b5b2e..34fec91 100644
--- a/docs/app/pages/[package]/index.vue
+++ b/docs/app/pages/[package]/index.vue
@@ -1,5 +1,7 @@
-<script setup lang="ts">const route = useRoute();
-const { getPackage, countEntries } = useDocs();
+<script setup lang="ts">import { sections } from '#docs/sections';
+
+const route = useRoute();
+const { getPackage, countEntries, getIntro } = useDocs();
 
 const slug = computed(() => route.params.package as string);
 const pkg = computed(() => getPackage(slug.value));
@@ -8,6 +10,10 @@ if (!pkg.value) {
   throw createError({ statusCode: 404, message: `Package "${slug.value}" not found` });
 }
 
+// Hand-authored intro (docs/intro.vue) renders as the package hero when present.
+const intro = computed(() => getIntro(pkg.value!));
+const introComponent = computed(() => intro.value ? sections[`${slug.value}/introduction`] ?? null : null);
+
 useHead({ title: `${pkg.value.name} — @robonen/tools` });
 
 const kindLabel = computed(() => ({
@@ -27,9 +33,14 @@ const otherSections = computed(() =>
 
 <template>
   <div v-if="pkg" class="max-w-3xl">
-    <!-- Header -->
-    <header class="mb-8 pb-8 border-b border-(--border)">
-      <div class="flex items-center gap-2.5 mb-2">
+    <!-- Hand-authored intro hero (docs/intro.vue) -->
+    <section v-if="introComponent" class="docs-section mb-12">
+      <component :is="introComponent" />
+    </section>
+
+    <!-- Auto header (shown only when there's no hand-authored intro) -->
+    <header v-else class="mb-8 pb-8 border-b border-(--border)">
+      <div class="flex items-center gap-2.5 mb-2 flex-wrap">
         <h1 class="font-mono text-2xl font-bold tracking-tight text-(--fg)">{{ pkg.name }}</h1>
         <DocsTag :label="`v${pkg.version}`" variant="neutral" />
       </div>
@@ -44,6 +55,11 @@ const otherSections = computed(() =>
       </div>
     </header>
 
+    <!-- When an intro replaces the header, label the auto-generated reference -->
+    <h2 v-if="introComponent && pkg.kind === 'api'" class="text-xs font-semibold uppercase tracking-wider text-(--fg-subtle) mb-4 pt-2">
+      API Reference
+    </h2>
+
     <!-- API: categories of items -->
     <template v-if="pkg.kind === 'api'">
       <section v-for="category in pkg.categories" :key="category.slug" class="mb-10">
@@ -51,7 +67,7 @@ const otherSections = computed(() =>
           {{ category.name }}
           <span class="ml-1 text-(--fg-subtle) normal-case font-normal">· {{ category.items.length }}</span>
         </h2>
-        <div class="grid gap-2">
+        <div class="grid grid-cols-1 gap-2">
           <NuxtLink
             v-for="item in category.items"
             :key="item.slug"
@@ -81,7 +97,7 @@ const otherSections = computed(() =>
         <h2 class="text-xs font-semibold uppercase tracking-wider text-(--fg-subtle) mb-4">
           All components <span class="normal-case font-normal">· {{ pkg.components.length }}</span>
         </h2>
-        <div class="grid gap-3 sm:grid-cols-2">
+        <div class="grid grid-cols-1 gap-3 sm:grid-cols-2">
           <NuxtLink
             v-for="c in pkg.components"
             :key="c.slug"
@@ -113,7 +129,7 @@ const otherSections = computed(() =>
       <DocsMarkdown v-if="overview" :source="overview.markdown" />
       <section v-if="otherSections.length > 0" class="mt-10 pt-8 border-t border-(--border)">
         <h2 class="text-xs font-semibold uppercase tracking-wider text-(--fg-subtle) mb-4">Sections</h2>
-        <div class="grid gap-2 sm:grid-cols-2">
+        <div class="grid grid-cols-1 gap-2 sm:grid-cols-2">
           <NuxtLink
             v-for="s in otherSections"
             :key="s.slug"
diff --git a/docs/app/pages/index.vue b/docs/app/pages/index.vue
index 9951530..ab2769a 100644
--- a/docs/app/pages/index.vue
+++ b/docs/app/pages/index.vue
@@ -39,7 +39,7 @@ useHead({ title: '@robonen/tools — Documentation' });
       <h2 class="text-xs font-semibold uppercase tracking-wider text-(--fg-subtle) mb-4">
         {{ grp.label }}
       </h2>
-      <div class="grid gap-3 sm:grid-cols-2">
+      <div class="grid grid-cols-1 gap-3 sm:grid-cols-2">
         <NuxtLink
           v-for="pkg in grp.packages"
           :key="pkg.slug"
diff --git a/docs/modules/extractor/extract.ts b/docs/modules/extractor/extract.ts
index ea8b198..810b7c0 100644
--- a/docs/modules/extractor/extract.ts
+++ b/docs/modules/extractor/extract.ts
@@ -18,6 +18,7 @@ import type {
   CategoryMeta,
   ComponentMeta,
   ComponentPartMeta,
+  DocSection,
   DocsMetadata,
   EmitMeta,
   GuideSection,
@@ -56,6 +57,7 @@ const PACKAGES: PackageConfig[] = [
   { path: 'core/platform', slug: 'platform', kind: 'api', group: 'core' },
   { path: 'core/fetch', slug: 'fetch', kind: 'api', group: 'core' },
   { path: 'core/encoding', slug: 'encoding', kind: 'api', group: 'core' },
+  { path: 'core/crdt', slug: 'crdt', kind: 'api', group: 'core' },
   // ── vue ──
   { path: 'vue/toolkit', slug: 'vue', kind: 'api', group: 'vue' },
   { path: 'vue/editor', slug: 'editor', kind: 'api', group: 'vue' },
@@ -72,8 +74,8 @@ const PACKAGES: PackageConfig[] = [
 
 function toKebabCase(str: string): string {
   return str
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .replaceAll(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replaceAll(/([A-Z])([A-Z][a-z])/g, '$1-$2')
     .toLowerCase();
 }
 
@@ -375,7 +377,7 @@ function extractTypeAlias(typeAlias: TypeAliasDeclaration, sourceFilePath: strin
   };
 }
 
-function collectExportedItems(sourceFile: SourceFile, entryPoint: string, visited: Set<string> = new Set()): ItemMeta[] {
+function collectExportedItems(sourceFile: SourceFile, entryPoint: string, visited = new Set<string>()): ItemMeta[] {
   const filePath = sourceFile.getFilePath();
   if (visited.has(filePath)) return [];
   visited.add(filePath);
@@ -656,7 +658,7 @@ function readPartOrder(indexPath: string): string[] {
   if (!existsSync(indexPath)) return [];
   const src = readFileSync(indexPath, 'utf-8');
   const order: string[] = [];
-  const re = /export\s*\{\s*default\s+as\s+(\w+)\s*\}\s*from\s*['"]\.\/([\w.-]+)\.vue['"]/g;
+  const re = /export\s*\{\s*default\s+as\s+(\w+)\s*\}\s*from\s*['"]\.\/[\w.-]+\.vue['"]/g;
   let m: RegExpExecArray | null;
   while ((m = re.exec(src)) !== null) order.push(m[1]!);
   return order;
@@ -751,7 +753,7 @@ function resolveGuideFiles(pkgDir: string, patterns: string[]): string[] {
 }
 
 function titleFromMarkdown(md: string, fallback: string): string {
-  const m = md.match(/^\s*#\s+(.+)$/m);
+  const m = md.match(/^\s*#\s+(\S.*)$/m);
   return m ? m[1]!.trim() : fallback;
 }
 
@@ -783,6 +785,65 @@ function buildGuideSections(pkgDir: string, patterns: string[], pkgDescription:
   return sections;
 }
 
+// ── Hand-authored .vue doc sections ─────────────────────────────────────────────
+
+/** Read an optional `<!-- key: value -->` directive from a doc SFC. */
+function readDocDirective(src: string, key: string): string | undefined {
+  const m = src.match(new RegExp(`<!--\\s*${key}\\s*:\\s*([^]*?)\\s*-->`));
+  return m ? m[1]!.trim() : undefined;
+}
+
+function humanizeTitle(slug: string): string {
+  return slug
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * Discover hand-authored documentation pages from `<pkg>/docs/*.vue`.
+ *  - `intro.vue` becomes the package landing (isIntro, sorted first).
+ *  - Other files are ordered by a `<!-- order: N -->` directive or a numeric
+ *    filename prefix (`02-concepts.vue`); titles come from `<!-- title: … -->`
+ *    or the humanized filename.
+ */
+function buildDocSections(pkgDir: string): DocSection[] {
+  const docsDir = resolve(pkgDir, 'docs');
+  if (!existsSync(docsDir)) return [];
+
+  const sections: DocSection[] = [];
+  for (const file of readdirSync(docsDir)) {
+    if (!file.endsWith('.vue')) continue;
+
+    const full = resolve(docsDir, file);
+    const src = readFileSync(full, 'utf-8');
+    const base = file.replace(/\.vue$/, '');
+    const isIntro = base === 'intro';
+
+    // Optional numeric prefix on the filename, e.g. "02-concepts" or "02.concepts".
+    const prefixed = base.match(/^(\d+)[-.](.+)$/);
+    const rawName = prefixed ? prefixed[2]! : base;
+
+    const orderDirective = readDocDirective(src, 'order');
+    const order = isIntro
+      ? -1
+      : orderDirective !== undefined
+        ? Number(orderDirective)
+        : prefixed
+          ? Number(prefixed[1])
+          : 100;
+
+    const slug = isIntro ? 'introduction' : slugify(rawName);
+    const title = readDocDirective(src, 'title')
+      ?? (isIntro ? 'Introduction' : humanizeTitle(rawName));
+
+    sections.push({ title, slug, order, isIntro, sourcePath: relative(ROOT, full) });
+  }
+
+  return sections.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+}
+
 // ── Package Extraction ─────────────────────────────────────────────────────────
 
 function extractPackage(config: PackageConfig): PackageMeta | null {
@@ -807,6 +868,7 @@ function extractPackage(config: PackageConfig): PackageMeta | null {
     categories: [],
     components: [],
     sections: [],
+    docs: buildDocSections(pkgDir),
   };
 
   if (config.kind === 'api') {
diff --git a/docs/modules/extractor/index.ts b/docs/modules/extractor/index.ts
index ee676f9..04c6d2a 100644
--- a/docs/modules/extractor/index.ts
+++ b/docs/modules/extractor/index.ts
@@ -65,6 +65,17 @@ export default defineNuxtModule({
     // Register the alias for the virtual module
     nuxt.options.alias['#docs/metadata'] = resolve(nuxt.options.buildDir, 'docs-metadata');
 
+    // Expose the same metadata to Nitro so server routes (e.g. the MCP endpoint
+    // at `server/routes/mcp.post.ts`) can import it without re-running extraction.
+    nuxt.hook('nitro:config', (nitroConfig: { virtual?: Record<string, string | (() => string)> }) => {
+      nitroConfig.virtual ??= {};
+      // Base64-encode the payload so Nitro's build-time text replacements (e.g.
+      // `typeof window` → "undefined") can't corrupt source snippets embedded in
+      // the metadata JSON (demo sources, examples, type signatures).
+      const encoded = Buffer.from(JSON.stringify(metadata), 'utf8').toString('base64');
+      nitroConfig.virtual['#docs/server-metadata'] = () => `export default JSON.parse(Buffer.from(${JSON.stringify(encoded)}, 'base64').toString('utf8'))`;
+    });
+
     // Add types reference
     addTemplate({
       filename: 'docs-metadata-types.d.ts',
@@ -89,6 +100,11 @@ declare module '#docs/metadata' {
       for (const pkg of metadata.packages) {
         routes.add(`/${pkg.slug}`);
 
+        // Hand-authored doc sections (any kind). The intro renders on the
+        // package landing, so only non-intro sections get their own route.
+        for (const section of pkg.docs)
+          if (!section.isIntro) routes.add(`/${pkg.slug}/${section.slug}`);
+
         if (pkg.kind === 'api') {
           for (const category of pkg.categories)
             for (const item of category.items)
@@ -113,6 +129,14 @@ declare module '#docs/metadata' {
       write: true,
       getContents: () => {
         const entries: string[] = [];
+        // An item re-exported from several entry points yields the same key more
+        // than once; dedupe so the generated object literal has no duplicate keys.
+        const seen = new Set<string>();
+        const add = (key: string, demoPath: string) => {
+          if (seen.has(key)) return;
+          seen.add(key);
+          entries.push(`  '${key}': defineAsyncComponent(() => import('${demoPath}')),`);
+        };
 
         for (const pkg of metadata.packages) {
           // api items
@@ -120,7 +144,7 @@ declare module '#docs/metadata' {
             for (const item of cat.items) {
               if (item.hasDemo) {
                 const demoPath = resolve(ROOT, dirname(item.sourcePath), 'demo.vue');
-                entries.push(`  '${pkg.slug}/${item.slug}': defineAsyncComponent(() => import('${demoPath}')),`);
+                add(`${pkg.slug}/${item.slug}`, demoPath);
               }
             }
           }
@@ -128,7 +152,7 @@ declare module '#docs/metadata' {
           for (const component of pkg.components) {
             if (component.hasDemo) {
               const demoPath = resolve(ROOT, component.sourcePath, 'demo.vue');
-              entries.push(`  '${pkg.slug}/${component.slug}': defineAsyncComponent(() => import('${demoPath}')),`);
+              add(`${pkg.slug}/${component.slug}`, demoPath);
             }
           }
         }
@@ -159,6 +183,48 @@ import type { Component } from 'vue';
 declare module '#docs/demos' {
   export const demos: Record<string, Component>;
 }
+`,
+    });
+
+    // Generate hand-authored doc-section import map (`<pkg>/docs/*.vue`)
+    addTemplate({
+      filename: 'docs-sections.ts',
+      write: true,
+      getContents: () => {
+        const entries: string[] = [];
+        for (const pkg of metadata.packages) {
+          for (const section of pkg.docs) {
+            const sectionPath = resolve(ROOT, section.sourcePath);
+            entries.push(`  '${pkg.slug}/${section.slug}': defineAsyncComponent(() => import('${sectionPath}')),`);
+          }
+        }
+
+        if (entries.length === 0) {
+          return `import type { Component } from 'vue';\nexport const sections: Record<string, Component> = {};\n`;
+        }
+
+        return [
+          `import { defineAsyncComponent } from 'vue';`,
+          `import type { Component } from 'vue';`,
+          ``,
+          `export const sections: Record<string, Component> = {`,
+          ...entries,
+          `};`,
+          ``,
+        ].join('\n');
+      },
+    });
+
+    nuxt.options.alias['#docs/sections'] = resolve(nuxt.options.buildDir, 'docs-sections');
+
+    addTemplate({
+      filename: 'docs-sections-types.d.ts',
+      write: true,
+      getContents: () => `
+import type { Component } from 'vue';
+declare module '#docs/sections' {
+  export const sections: Record<string, Component>;
+}
 `,
     });
   },
diff --git a/docs/modules/extractor/types.ts b/docs/modules/extractor/types.ts
index 5021787..f9f5533 100644
--- a/docs/modules/extractor/types.ts
+++ b/docs/modules/extractor/types.ts
@@ -46,6 +46,14 @@ export interface PackageMeta {
   // ── kind: 'guide' ──────────────────────────────────────────────────────────
   /** Prose sections rendered from Markdown (kind === 'guide') */
   sections: GuideSection[];
+
+  // ── any kind ───────────────────────────────────────────────────────────────
+  /**
+   * Hand-authored `.vue` documentation pages discovered from `<pkg>/docs/*.vue`.
+   * Independent of `kind` — an `api` package can still ship a rich intro and
+   * several prose sections alongside its auto-generated reference.
+   */
+  docs: DocSection[];
 }
 
 // ── API kind ─────────────────────────────────────────────────────────────────
@@ -152,6 +160,21 @@ export interface GuideSection {
   markdown: string;
 }
 
+// ── Hand-authored .vue doc sections (any kind) ──────────────────────────────────
+
+export interface DocSection {
+  /** Display title (from a `<!-- title: … -->` comment or the filename). */
+  title: string;
+  /** URL-friendly slug, e.g. "introduction" or "concepts". */
+  slug: string;
+  /** Sort order (from a `<!-- order: N -->` comment or a numeric filename prefix). */
+  order: number;
+  /** `true` for `docs/intro.vue` — rendered as the package landing page. */
+  isIntro: boolean;
+  /** Relative path to the `.vue` file from repo root (for the GitHub source link). */
+  sourcePath: string;
+}
+
 // ── Shared leaf types ──────────────────────────────────────────────────────────
 
 export interface ParamMeta {
diff --git a/docs/modules/mcp/README.md b/docs/modules/mcp/README.md
new file mode 100644
index 0000000..708a4d1
--- /dev/null
+++ b/docs/modules/mcp/README.md
@@ -0,0 +1,65 @@
+# Docs MCP server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the `@robonen/tools`
+documentation to any MCP client (Claude Code, Claude Desktop, Cursor, …).
+
+It is **served by the Nuxt/Nitro docs server itself** — there is no separate
+process. The documentation metadata is the same data that renders the docs site
+(produced by [`../extractor`](../extractor) at build time and injected into Nitro
+as the `#docs/server-metadata` virtual), so what an agent reads is always in sync
+with the site.
+
+## Run
+
+Start the docs server, and the MCP endpoint comes up with it:
+
+```sh
+pnpm docs:dev      # → http://localhost:3000, MCP at http://localhost:3000/mcp
+```
+
+`POST /mcp` speaks the MCP **Streamable HTTP** transport (stateless, JSON
+responses). The route lives at [`../../server/routes/mcp.post.ts`](../../server/routes/mcp.post.ts).
+
+## Register with a client
+
+A project-scoped [`.mcp.json`](../../../.mcp.json) at the repo root already points
+Claude Code at the endpoint — start the docs server, then approve the
+`robonen-docs` server:
+
+```json
+{
+  "mcpServers": {
+    "robonen-docs": { "type": "http", "url": "http://localhost:3000/mcp" }
+  }
+}
+```
+
+## Tools
+
+| Tool            | Arguments                       | Returns                                                                 |
+| --------------- | ------------------------------- | ----------------------------------------------------------------------- |
+| `list_packages` | —                               | Every documented package grouped by core / vue / configs / infra.       |
+| `search_docs`   | `query`, `limit?`               | Ranked `package/slug` matches across items, components and guides.      |
+| `get_package`   | `slug`                          | A package's table of contents (categories, components or sections).     |
+| `get_doc`       | `package`, `name`               | Full reference for one item: signatures, params, examples, props/emits. |
+
+`name` accepts either the URL slug (`use-clipboard`) or the exported name
+(`useClipboard`). Slugs are unique within a package; case-only collisions (e.g.
+the `useProjection` function vs the `UseProjection` type) are disambiguated with
+a kind suffix (`use-projection-type`).
+
+## Resources
+
+- `robonen-docs://index` — the documentation index.
+- `robonen-docs://{package}/{slug}` — full Markdown for a single documented item
+  (listable, one entry per leaf).
+
+## Layout
+
+| File                                  | Responsibility                                                          |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `../../server/routes/mcp.post.ts`     | Nitro HTTP route — bridges the request to the MCP transport.            |
+| `create-server.ts`                    | Builds the configured `McpServer` (tools + resources) from metadata.   |
+| `docs-index.ts`                       | Pure query layer — flatten, unique-slug, search, resolve.              |
+| `format.ts`                           | Markdown renderers for tool/resource payloads.                          |
+| `*.test.ts`                           | Unit tests for the query layer.                                         |
diff --git a/docs/modules/mcp/create-server.ts b/docs/modules/mcp/create-server.ts
new file mode 100644
index 0000000..58b71b1
--- /dev/null
+++ b/docs/modules/mcp/create-server.ts
@@ -0,0 +1,160 @@
+/**
+ * Builds a configured MCP server exposing the @robonen/tools documentation.
+ *
+ * Transport-agnostic: the same server is mounted on the Nuxt/Nitro HTTP route
+ * (see `docs/server/routes/mcp.post.ts`). Given already-extracted
+ * {@link DocsMetadata}, it registers the docs tools and resources.
+ */
+
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { DocsMetadata } from '../extractor/types';
+import type { Leaf } from './docs-index';
+import { buildLeaves, getPackage, resolveEntry, search } from './docs-index';
+import {
+  renderDocEntry,
+  renderPackageList,
+  renderPackageOverview,
+  renderSearchResults,
+} from './format';
+
+const INSTRUCTIONS = [
+  'Documentation for the @robonen/tools monorepo (core utilities, Vue composables &',
+  'primitives, shared configs). Workflow: call `list_packages` to see what exists,',
+  '`search_docs` to find an item by keyword, `get_package` for a package\'s table of',
+  'contents, and `get_doc` for the full reference (signatures, params, examples,',
+  'props/emits, demo source) of one item. Slugs are kebab-case; names are as exported.',
+].join(' ');
+
+/** Wrap a not-found message as a non-fatal tool error. */
+function toolError(message: string) {
+  return { content: [{ type: 'text' as const, text: message }], isError: true };
+}
+
+/** Wrap rendered Markdown as a successful tool result. */
+function toolText(text: string) {
+  return { content: [{ type: 'text' as const, text }] };
+}
+
+function registerTools(server: McpServer, metadata: DocsMetadata, leaves: Leaf[]): void {
+  server.registerTool(
+    'list_packages',
+    {
+      title: 'List documentation packages',
+      description:
+        'List every documented @robonen/tools package (core, vue, configs, infra) with its kind, '
+        + 'version, description and entry count. Start here to discover what is available.',
+      inputSchema: {},
+    },
+    async () => toolText(renderPackageList(metadata)),
+  );
+
+  server.registerTool(
+    'search_docs',
+    {
+      title: 'Search documentation',
+      description:
+        'Full-text search across all documented functions, classes, types, components and guide '
+        + 'sections. Returns ranked matches as `package/slug` references to pass to get_doc.',
+      inputSchema: {
+        query: z.string().min(1).describe('Search terms, e.g. "debounce", "clipboard", "eslint imports".'),
+        limit: z.number().int().min(1).max(50).optional().describe('Maximum number of results (default 20).'),
+      },
+    },
+    async ({ query, limit }) => toolText(renderSearchResults(search(leaves, query, limit ?? 20), query)),
+  );
+
+  server.registerTool(
+    'get_package',
+    {
+      title: 'Get a package overview',
+      description:
+        'Show a package\'s full table of contents: categories and items (api), components and their '
+        + 'parts (components), or sections (guide). Pass the package slug from list_packages.',
+      inputSchema: {
+        slug: z.string().min(1).describe('Package slug, e.g. "stdlib", "toolkit", "primitives".'),
+      },
+    },
+    async ({ slug }) => {
+      const pkg = getPackage(metadata, slug);
+      if (!pkg) return toolError(`No package with slug "${slug}". Call list_packages to see available slugs.`);
+      return toolText(renderPackageOverview(pkg));
+    },
+  );
+
+  server.registerTool(
+    'get_doc',
+    {
+      title: 'Get full documentation for an item',
+      description:
+        'Return the complete documentation for a single function, class, type, component or guide '
+        + 'section: signatures, parameters, return type, examples, props/emits, demo source and the '
+        + 'source path. Pass the package slug plus the item slug or its exported name.',
+      inputSchema: {
+        package: z.string().min(1).describe('Package slug, e.g. "stdlib".'),
+        name: z.string().min(1).describe('Item slug or exported name, e.g. "clamp" or "useClipboard".'),
+      },
+    },
+    async ({ package: pkgSlug, name }) => {
+      const entry = resolveEntry(leaves, pkgSlug, name);
+      if (!entry) {
+        return toolError(
+          `No documented item "${name}" in package "${pkgSlug}". Call get_package("${pkgSlug}") to list its items.`,
+        );
+      }
+      return toolText(renderDocEntry(entry));
+    },
+  );
+}
+
+function registerResources(server: McpServer, metadata: DocsMetadata, leaves: Leaf[]): void {
+  // The whole table of contents as a single browsable resource.
+  server.registerResource(
+    'docs-index',
+    'robonen-docs://index',
+    {
+      title: '@robonen/tools documentation index',
+      description: 'Table of contents for every documented package.',
+      mimeType: 'text/markdown',
+    },
+    async uri => ({
+      contents: [{ uri: uri.href, mimeType: 'text/markdown', text: renderPackageList(metadata) }],
+    }),
+  );
+
+  // One resource per documented leaf, addressable as robonen-docs://<package>/<slug>.
+  server.registerResource(
+    'docs-entry',
+    new ResourceTemplate('robonen-docs://{package}/{slug}', {
+      list: async () => ({
+        resources: leaves.map(leaf => ({
+          uri: `robonen-docs://${leaf.packageSlug}/${leaf.slug}`,
+          name: `${leaf.packageName} / ${leaf.name}`,
+          description: leaf.description || `${leaf.badge} in ${leaf.packageName}`,
+          mimeType: 'text/markdown',
+        })),
+      }),
+    }),
+    {
+      title: 'Documentation entry',
+      description: 'Full documentation for a single documented item.',
+      mimeType: 'text/markdown',
+    },
+    async (uri, variables) => {
+      const pkgSlug = String(variables.package);
+      const slug = String(variables.slug);
+      const entry = resolveEntry(leaves, pkgSlug, slug);
+      if (!entry) throw new Error(`Unknown documentation resource: ${uri.href}`);
+      return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: renderDocEntry(entry) }] };
+    },
+  );
+}
+
+/** Build an MCP server for the given documentation metadata, ready to connect to a transport. */
+export function createDocsMcpServer(metadata: DocsMetadata, version = '0.0.0'): McpServer {
+  const leaves = buildLeaves(metadata);
+  const server = new McpServer({ name: 'robonen-docs', version }, { instructions: INSTRUCTIONS });
+  registerTools(server, metadata, leaves);
+  registerResources(server, metadata, leaves);
+  return server;
+}
diff --git a/docs/modules/mcp/docs-index.test.ts b/docs/modules/mcp/docs-index.test.ts
new file mode 100644
index 0000000..bd5df48
--- /dev/null
+++ b/docs/modules/mcp/docs-index.test.ts
@@ -0,0 +1,232 @@
+import { describe, expect, it } from 'vitest';
+import type { DocsMetadata, ItemMeta } from '../extractor/types';
+import { buildLeaves, countEntries, getPackage, groupPackages, resolveEntry, search } from './docs-index';
+
+function item(partial: Partial<ItemMeta> & Pick<ItemMeta, 'name' | 'slug' | 'kind' | 'description'>): ItemMeta {
+  return {
+    since: '',
+    signatures: [],
+    params: [],
+    returns: null,
+    typeParams: [],
+    examples: [],
+    methods: [],
+    properties: [],
+    hasDemo: false,
+    demoSource: '',
+    hasTests: false,
+    relatedTypes: [],
+    sourcePath: '',
+    entryPoint: '.',
+    ...partial,
+  };
+}
+
+const metadata: DocsMetadata = {
+  generatedAt: '2026-06-08T00:00:00.000Z',
+  packages: [
+    {
+      name: '@robonen/stdlib',
+      version: '1.0.0',
+      description: 'Standard library utilities',
+      slug: 'stdlib',
+      kind: 'api',
+      group: 'core',
+      entryPoints: ['.'],
+      categories: [
+        {
+          name: 'Numbers',
+          slug: 'numbers',
+          items: [
+            item({ name: 'clamp', slug: 'clamp', kind: 'function', description: 'Clamp a number to a range' }),
+            item({ name: 'debounce', slug: 'debounce', kind: 'function', description: 'Debounce a function call' }),
+          ],
+        },
+      ],
+      components: [],
+      sections: [],
+    },
+    {
+      name: '@robonen/toolkit',
+      version: '2.0.0',
+      description: 'Vue composables',
+      slug: 'toolkit',
+      kind: 'components',
+      group: 'vue',
+      entryPoints: ['.'],
+      categories: [],
+      components: [
+        {
+          name: 'useClipboard',
+          slug: 'use-clipboard',
+          description: 'Reactive clipboard access',
+          entryPoint: './use-clipboard',
+          parts: [],
+          hasDemo: false,
+          demoSource: '',
+          sourcePath: '',
+        },
+      ],
+      sections: [],
+    },
+    {
+      name: '@robonen/eslint',
+      version: '3.0.0',
+      description: 'Shared ESLint config',
+      slug: 'eslint',
+      kind: 'guide',
+      group: 'configs',
+      entryPoints: ['.'],
+      categories: [],
+      components: [],
+      sections: [
+        { title: 'Imports preset', slug: 'imports', markdown: '# Imports\nSorts and dedupes imports.' },
+      ],
+    },
+  ],
+};
+
+describe('buildLeaves', () => {
+  it('flattens every leaf across all package kinds', () => {
+    const leaves = buildLeaves(metadata);
+    expect(leaves).toHaveLength(4);
+    expect(leaves.map(l => l.slug).sort()).toEqual(['clamp', 'debounce', 'imports', 'use-clipboard']);
+  });
+
+  it('tags each leaf with the right badge', () => {
+    const byName = new Map(buildLeaves(metadata).map(l => [l.name, l.badge]));
+    expect(byName.get('clamp')).toBe('function');
+    expect(byName.get('useClipboard')).toBe('component');
+    expect(byName.get('Imports preset')).toBe('guide');
+  });
+});
+
+describe('search', () => {
+  const leaves = buildLeaves(metadata);
+
+  it('returns empty for a blank query', () => {
+    expect(search(leaves, '   ')).toEqual([]);
+  });
+
+  it('ranks an exact name match first', () => {
+    const hits = search(leaves, 'clamp');
+    expect(hits[0]?.name).toBe('clamp');
+    expect(hits[0]?.packageSlug).toBe('stdlib');
+  });
+
+  it('matches on description body, not just names', () => {
+    const hits = search(leaves, 'clipboard');
+    expect(hits.map(h => h.name)).toContain('useClipboard');
+  });
+
+  it('applies AND semantics across tokens', () => {
+    expect(search(leaves, 'clamp clipboard')).toEqual([]);
+  });
+
+  it('honours the limit', () => {
+    expect(search(leaves, 'a', 1)).toHaveLength(1);
+  });
+});
+
+describe('getPackage / resolveEntry', () => {
+  const leaves = buildLeaves(metadata);
+
+  it('finds a package by slug, case-insensitively', () => {
+    expect(getPackage(metadata, 'STDLIB')?.name).toBe('@robonen/stdlib');
+    expect(getPackage(metadata, 'nope')).toBeUndefined();
+  });
+
+  it('resolves an api item by slug or exported name', () => {
+    expect(resolveEntry(leaves, 'stdlib', 'clamp')?.kind).toBe('api');
+    expect(resolveEntry(leaves, 'stdlib', 'Clamp')?.kind).toBe('api');
+  });
+
+  it('resolves a component by slug and by name', () => {
+    expect(resolveEntry(leaves, 'toolkit', 'use-clipboard')?.kind).toBe('components');
+    expect(resolveEntry(leaves, 'toolkit', 'useClipboard')?.kind).toBe('components');
+  });
+
+  it('resolves a guide section', () => {
+    const entry = resolveEntry(leaves, 'eslint', 'imports');
+    expect(entry?.kind).toBe('guide');
+  });
+
+  it('returns undefined for an unknown item', () => {
+    expect(resolveEntry(leaves, 'stdlib', 'missing')).toBeUndefined();
+  });
+});
+
+describe('slug uniqueness & collisions', () => {
+  // A function and a co-located type/interface whose names differ only in case
+  // both slugify to the same value — the real extractor produces these in
+  // @robonen/editor and @robonen/vue.
+  const colliding: DocsMetadata = {
+    generatedAt: '2026-06-08T00:00:00.000Z',
+    packages: [
+      {
+        name: '@robonen/editor',
+        version: '1.0.0',
+        description: 'Editor',
+        slug: 'editor',
+        kind: 'api',
+        group: 'vue',
+        entryPoints: ['.'],
+        categories: [
+          {
+            name: 'Model',
+            slug: 'model',
+            items: [
+              item({ name: 'position', slug: 'position', kind: 'function', description: 'Create a position' }),
+              item({ name: 'Position', slug: 'position', kind: 'interface', description: 'A position' }),
+            ],
+          },
+        ],
+        components: [],
+        sections: [],
+      },
+    ],
+  };
+
+  it('disambiguates colliding slugs so every (package, slug) pair is unique', () => {
+    const leaves = buildLeaves(colliding);
+    const slugs = leaves.map(l => l.slug);
+    expect(slugs).toEqual(['position', 'position-interface']);
+    expect(new Set(slugs).size).toBe(slugs.length);
+  });
+
+  it('reaches both colliding symbols — function and interface — independently', () => {
+    const leaves = buildLeaves(colliding);
+    // Exact case-sensitive name disambiguates the function from the interface.
+    const fn = resolveEntry(leaves, 'editor', 'position');
+    const iface = resolveEntry(leaves, 'editor', 'Position');
+    expect(fn?.kind === 'api' && fn.item.kind).toBe('function');
+    expect(iface?.kind === 'api' && iface.item.kind).toBe('interface');
+    // The disambiguated slug also resolves the interface directly.
+    const bySlug = resolveEntry(leaves, 'editor', 'position-interface');
+    expect(bySlug?.kind === 'api' && bySlug.item.kind).toBe('interface');
+  });
+
+  it('throws when a slug contains a URI-reserved character', () => {
+    const bad: DocsMetadata = {
+      generatedAt: '2026-06-08T00:00:00.000Z',
+      packages: [{
+        name: '@robonen/x', version: '1.0.0', description: '', slug: 'x', kind: 'guide', group: 'infra',
+        entryPoints: ['.'], categories: [], components: [],
+        sections: [{ title: 'Nested', slug: 'rules/no-foo', markdown: '#' }],
+      }],
+    };
+    expect(() => buildLeaves(bad)).toThrow(/reserved URI character/);
+  });
+});
+
+describe('grouping helpers', () => {
+  it('orders groups core → vue → configs and drops empties', () => {
+    expect(groupPackages(metadata).map(g => g.group)).toEqual(['core', 'vue', 'configs']);
+  });
+
+  it('counts entries per package kind', () => {
+    expect(countEntries(metadata.packages[0]!)).toBe(2);
+    expect(countEntries(metadata.packages[1]!)).toBe(1);
+    expect(countEntries(metadata.packages[2]!)).toBe(1);
+  });
+});
diff --git a/docs/modules/mcp/docs-index.ts b/docs/modules/mcp/docs-index.ts
new file mode 100644
index 0000000000000000000000000000000000000000..397e50a93cb989a353513a8efc91c53c206cd686
GIT binary patch
literal 9517
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

literal 0
HcmV?d00001

diff --git a/docs/modules/mcp/format.ts b/docs/modules/mcp/format.ts
new file mode 100644
index 0000000..46a4ca8
--- /dev/null
+++ b/docs/modules/mcp/format.ts
@@ -0,0 +1,274 @@
+/**
+ * Markdown renderers turning structured {@link DocsMetadata} into the text
+ * payloads returned by the MCP tools/resources. Output targets an LLM reader:
+ * compact, signature-first, code-fenced where it helps.
+ */
+
+import type {
+  ComponentMeta,
+  ComponentPartMeta,
+  DocsMetadata,
+  GuideSection,
+  ItemMeta,
+  MethodMeta,
+  PackageMeta,
+  ParamMeta,
+  PropertyMeta,
+} from '../extractor/types';
+import type { DocEntry, SearchHit } from './docs-index';
+import { countEntries, groupPackages } from './docs-index';
+
+/** Collapse whitespace and trim — keeps table cells on one line. */
+function inline(text: string): string {
+  return text.replaceAll(/\s+/g, ' ').trim();
+}
+
+/** Escape pipe / newline so a value is safe inside a Markdown table cell. */
+function cell(text: string): string {
+  const value = inline(text).replaceAll('|', '\\|');
+  return value.length > 0 ? value : '—';
+}
+
+/** A fenced code block; language defaults to `ts`. */
+function fence(code: string, lang = 'ts'): string {
+  return `\`\`\`${lang}\n${code.trim()}\n\`\`\``;
+}
+
+/** Maximum demo lines embedded verbatim before we truncate and link the source. */
+const MAX_DEMO_LINES = 140;
+
+/** A `## Demo` block, capped so a large demo.vue cannot bloat a single tool result. */
+function demoBlock(source: string, sourcePath: string): string[] {
+  const lines = source.trim().split('\n');
+  if (lines.length <= MAX_DEMO_LINES) return ['## Demo', '', fence(source, 'vue'), ''];
+  return [
+    '## Demo',
+    '',
+    fence(lines.slice(0, MAX_DEMO_LINES).join('\n'), 'vue'),
+    `_Demo truncated to ${MAX_DEMO_LINES} of ${lines.length} lines — full source: \`${sourcePath}\`._`,
+    '',
+  ];
+}
+
+/** Render a GitHub-flavoured Markdown table from a header + rows. */
+function table(header: string[], rows: string[][]): string {
+  const head = `| ${header.join(' | ')} |`;
+  const divider = `| ${header.map(() => '---').join(' | ')} |`;
+  const body = rows.map(r => `| ${r.join(' | ')} |`).join('\n');
+  return [head, divider, body].join('\n');
+}
+
+/** A required/optional name with its default, formatted for a table cell. */
+function paramName(p: ParamMeta | PropertyMeta): string {
+  const base = p.optional ? `${p.name}?` : p.name;
+  return p.defaultValue ? `${base} = ${p.defaultValue}` : base;
+}
+
+// ── Package list (table of contents) ─────────────────────────────────────────
+
+export function renderPackageList(metadata: DocsMetadata): string {
+  const lines: string[] = ['# @robonen/tools — documentation index', ''];
+
+  for (const { label, packages } of groupPackages(metadata)) {
+    lines.push(`## ${label}`, '');
+    for (const pkg of packages) {
+      const count = countEntries(pkg);
+      const noun = pkg.kind === 'api' ? 'items' : pkg.kind === 'components' ? 'components' : 'sections';
+      lines.push(
+        `- **${pkg.slug}** — \`${pkg.name}\`@${pkg.version} · _${pkg.kind}_ · ${count} ${noun}${
+          pkg.description ? `\n  ${inline(pkg.description)}` : ''}`,
+      );
+    }
+    lines.push('');
+  }
+
+  lines.push(
+    '---',
+    `${metadata.packages.length} packages · generated ${metadata.generatedAt}`,
+    'Use `get_package(slug)` for a package\'s contents, then `get_doc(package, name)` for full detail.',
+  );
+
+  return lines.join('\n');
+}
+
+// ── Package overview ─────────────────────────────────────────────────────────
+
+export function renderPackageOverview(pkg: PackageMeta): string {
+  const lines: string[] = [`# ${pkg.name}@${pkg.version}`, ''];
+  if (pkg.description) lines.push(inline(pkg.description), '');
+  lines.push(`_kind: ${pkg.kind} · group: ${pkg.group} · entry points: ${pkg.entryPoints.join(', ')}_`, '');
+
+  if (pkg.kind === 'api') {
+    for (const category of pkg.categories) {
+      lines.push(`## ${category.name}`, '');
+      for (const item of category.items) {
+        lines.push(`- \`${item.name}\` · _${item.kind}_${item.description ? ` — ${inline(item.description)}` : ''}`);
+      }
+      lines.push('');
+    }
+  }
+  else if (pkg.kind === 'components') {
+    lines.push('## Components', '');
+    for (const c of pkg.components) {
+      const parts = c.parts.map(p => p.name).join(', ');
+      lines.push(`- **${c.name}** (\`${c.slug}\`)${c.description ? ` — ${inline(c.description)}` : ''}`);
+      if (parts) lines.push(`  parts: ${parts}`);
+    }
+    lines.push('');
+  }
+  else {
+    lines.push('## Sections', '');
+    for (const s of pkg.sections) lines.push(`- **${s.title}** (\`${s.slug}\`)`);
+    lines.push('');
+  }
+
+  lines.push('---', `Use \`get_doc("${pkg.slug}", name)\` for the full documentation of an item.`);
+  return lines.join('\n');
+}
+
+// ── Single entry ─────────────────────────────────────────────────────────────
+
+function renderParams(params: ParamMeta[]): string[] {
+  if (params.length === 0) return [];
+  const rows = params.map(p => [cell(paramName(p)), cell(`\`${p.type}\``), cell(p.description)]);
+  return ['## Parameters', '', table(['Parameter', 'Type', 'Description'], rows), ''];
+}
+
+function renderProperties(title: string, props: PropertyMeta[]): string[] {
+  if (props.length === 0) return [];
+  const rows = props.map(p => [
+    cell(`${paramName(p)}${p.readonly ? ' _(readonly)_' : ''}`),
+    cell(`\`${p.type}\``),
+    cell(p.description),
+  ]);
+  return [`## ${title}`, '', table(['Name', 'Type', 'Description'], rows), ''];
+}
+
+function renderMethods(methods: MethodMeta[]): string[] {
+  if (methods.length === 0) return [];
+  const out: string[] = ['## Methods', ''];
+  for (const m of methods) {
+    out.push(`### ${m.name}${m.visibility && m.visibility !== 'public' ? ` _(${m.visibility})_` : ''}`);
+    if (m.description) out.push('', inline(m.description));
+    if (m.signatures.length > 0) out.push('', fence(m.signatures.join('\n')));
+    out.push(...renderParams(m.params));
+    if (m.returns) out.push(`**Returns** \`${inline(m.returns.type)}\`${m.returns.description ? ` — ${inline(m.returns.description)}` : ''}`, '');
+  }
+  return out;
+}
+
+function renderApiItem(pkg: PackageMeta, item: ItemMeta): string {
+  const lines: string[] = [
+    `# ${item.name}`,
+    '',
+    `_${item.kind} · ${pkg.name}${item.since ? ` · since ${item.since}` : ''} · \`${item.entryPoint}\`_`,
+    '',
+  ];
+  if (item.description) lines.push(inline(item.description), '');
+
+  if (item.signatures.length > 0) {
+    lines.push('## Signature', '', fence(item.signatures.join('\n\n')), '');
+  }
+
+  if (item.typeParams.length > 0) {
+    const rows = item.typeParams.map(tp => [
+      cell(tp.name),
+      cell(tp.constraint ? `\`${tp.constraint}\`` : '—'),
+      cell(tp.default ? `\`${tp.default}\`` : '—'),
+      cell(tp.description),
+    ]);
+    lines.push('## Type Parameters', '', table(['Name', 'Constraint', 'Default', 'Description'], rows), '');
+  }
+
+  lines.push(...renderParams(item.params));
+
+  if (item.returns) {
+    lines.push(
+      '## Returns',
+      '',
+      `\`${inline(item.returns.type)}\`${item.returns.description ? ` — ${inline(item.returns.description)}` : ''}`,
+      '',
+    );
+  }
+
+  lines.push(...renderMethods(item.methods));
+  lines.push(...renderProperties('Properties', item.properties));
+
+  if (item.examples.length > 0) {
+    lines.push('## Examples', '');
+    for (const ex of item.examples) lines.push(fence(ex), '');
+  }
+
+  if (item.relatedTypes.length > 0) {
+    lines.push('## Related Types', '');
+    for (const t of item.relatedTypes) {
+      lines.push(`### ${t.name}${t.description ? ` — ${inline(t.description)}` : ''}`);
+      if (t.signatures.length > 0) lines.push('', fence(t.signatures.join('\n')));
+      lines.push(...renderProperties('Properties', t.properties));
+      lines.push('');
+    }
+  }
+
+  if (item.hasDemo && item.demoSource) {
+    lines.push(...demoBlock(item.demoSource, item.sourcePath));
+  }
+
+  lines.push('---', `Source: \`${item.sourcePath}\`${item.hasTests ? ' · has tests' : ''}`);
+  return lines.join('\n');
+}
+
+function renderComponentPart(part: ComponentPartMeta): string[] {
+  const out: string[] = [`### ${part.name}${part.role ? ` _(${part.role})_` : ''}`];
+  if (part.description) out.push('', inline(part.description));
+  out.push(...renderProperties('Props', part.props));
+
+  if (part.emits.length > 0) {
+    const rows = part.emits.map(e => [cell(e.name), cell(`\`${e.payload}\``), cell(e.description)]);
+    out.push('#### Emits', '', table(['Event', 'Payload', 'Description'], rows), '');
+  }
+  return out;
+}
+
+function renderComponent(pkg: PackageMeta, component: ComponentMeta): string {
+  const lines: string[] = [`# ${component.name}`, '', `_component · ${pkg.name} · \`${component.entryPoint}\`_`, ''];
+  if (component.description) lines.push(inline(component.description), '');
+
+  lines.push('## Anatomy', '');
+  for (const part of component.parts) lines.push(...renderComponentPart(part));
+
+  if (component.hasDemo && component.demoSource) {
+    lines.push(...demoBlock(component.demoSource, component.sourcePath));
+  }
+
+  lines.push('---', `Source: \`${component.sourcePath}\``);
+  return lines.join('\n');
+}
+
+function renderGuide(pkg: PackageMeta, section: GuideSection): string {
+  return [`# ${section.title}`, '', `_guide · ${pkg.name}_`, '', section.markdown.trim()].join('\n');
+}
+
+/** Render any documented leaf to full Markdown. */
+export function renderDocEntry(entry: DocEntry): string {
+  if (entry.kind === 'api') return renderApiItem(entry.pkg, entry.item);
+  if (entry.kind === 'components') return renderComponent(entry.pkg, entry.component);
+  return renderGuide(entry.pkg, entry.section);
+}
+
+// ── Search results ───────────────────────────────────────────────────────────
+
+export function renderSearchResults(hits: SearchHit[], query: string): string {
+  if (hits.length === 0) {
+    return `No documentation matches "${query}". Try a broader term, or call list_packages to browse.`;
+  }
+
+  const lines: string[] = [`Found ${hits.length} result${hits.length === 1 ? '' : 's'} for "${query}":`, ''];
+  for (const hit of hits) {
+    lines.push(
+      `- **${hit.name}** · _${hit.badge}_ · \`${hit.packageSlug}/${hit.slug}\`${
+        hit.description ? `\n  ${inline(hit.description)}` : ''}`,
+    );
+  }
+  lines.push('', 'Call `get_doc(package, name)` with the `package/slug` above for full detail.');
+  return lines.join('\n');
+}
diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts
index 560098f..9223646 100644
--- a/docs/nuxt.config.ts
+++ b/docs/nuxt.config.ts
@@ -20,8 +20,18 @@ export default defineNuxtConfig({
 
   ssr: true,
 
+  // Dev-only: the file-based payload cache collides on parent+child routes that
+  // share a segment (e.g. `/vue` is written as a file while `/vue/*` needs `vue`
+  // to be a directory → ENOTDIR). Production prerender writes each route to its
+  // own dir, so payload extraction is left enabled there.
+  $development: {
+    experimental: { payloadExtraction: false },
+  },
+
   routeRules: {
     '/**': { prerender: true },
+    // The MCP endpoint is a dynamic POST handler — never prerender it.
+    '/mcp': { prerender: false },
   },
 
   nitro: {
diff --git a/docs/package.json b/docs/package.json
index b8244fd..36b8d23 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -15,8 +15,10 @@
     "extract": "jiti ./modules/extractor/extract.ts"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "marked": "^18.0.5",
-    "shiki": "^4.0.1"
+    "shiki": "^4.0.1",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@nuxt/fonts": "^0.14.0",
diff --git a/docs/server/routes/mcp.post.ts b/docs/server/routes/mcp.post.ts
new file mode 100644
index 0000000..176e296
--- /dev/null
+++ b/docs/server/routes/mcp.post.ts
@@ -0,0 +1,39 @@
+/**
+ * MCP endpoint, served by the Nuxt/Nitro server itself — no separate process.
+ *
+ * Speaks the MCP Streamable HTTP transport in stateless mode (one fresh server
+ * per request, plain JSON responses), reusing the shared `createDocsMcpServer`
+ * factory and the build-time documentation metadata injected by the extractor
+ * module as the `#docs/server-metadata` virtual.
+ *
+ * POST /mcp  →  start the dev server (`pnpm docs:dev`) and point your MCP client
+ * at http://localhost:3000/mcp.
+ */
+
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import metadata from '#docs/server-metadata';
+import pkg from '../../package.json';
+import { createDocsMcpServer } from '../../modules/mcp/create-server';
+
+export default defineEventHandler(async (event) => {
+  // h3 has already buffered the JSON body; hand it to the transport so it does
+  // not try to re-read the consumed request stream.
+  const body = await readBody(event);
+
+  const server = createDocsMcpServer(metadata, pkg.version);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined, // stateless: no session tracking for read-only docs
+    enableJsonResponse: true, // return a single JSON response rather than an SSE stream
+  });
+
+  // Tear both down once the response is flushed.
+  event.node.res.on('close', () => {
+    void transport.close();
+    void server.close();
+  });
+
+  await server.connect(transport);
+  // The transport writes the status, headers and body directly to res and ends
+  // it; h3 sees `res.writableEnded` and does not attempt a second response.
+  await transport.handleRequest(event.node.req, event.node.res, body);
+});
diff --git a/docs/server/types.d.ts b/docs/server/types.d.ts
new file mode 100644
index 0000000..f723e17
--- /dev/null
+++ b/docs/server/types.d.ts
@@ -0,0 +1,7 @@
+/** Types for the Nitro virtual module injected by `modules/extractor`. */
+declare module '#docs/server-metadata' {
+  import type { DocsMetadata } from '../modules/extractor/types';
+
+  const metadata: DocsMetadata;
+  export default metadata;
+}
diff --git a/docs/vitest.config.ts b/docs/vitest.config.ts
new file mode 100644
index 0000000..0b27d3f
--- /dev/null
+++ b/docs/vitest.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Only the build-time tooling (extractor / MCP server) is unit-tested here;
+    // the Nuxt app itself is covered elsewhere.
+    include: ['modules/**/*.test.ts'],
+    environment: 'node',
+  },
+});