@lupinum/ginko-docs 0.4.0-rc.9 → 0.5.0

package/package.json

@@ -1,103 +1,71 @@
 {
   "name": "@lupinum/ginko-docs",
-  "version": "0.4.0-rc.9",
-  "description": "A Nuxt documentation layer powered by Ginko Content.",
-  "keywords": [
-    "content",
-    "documentation",
-    "i18n",
-    "markdown",
-    "nuxt"
-  ],
-  "homepage": "https://ginko-docs.lupinum.com",
-  "bugs": {
-    "url": "https://github.com/lupinum-dev/ginko-docs/issues"
-  },
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Docs sites on Ginko: a Nuxt layer with navigation, search, blog, changelog and Markdown components.",
   "license": "MIT",
   "author": "Lupinum OG <info@lupinum.com> (https://lupinum.com)",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lupinum-dev/ginko-docs.git",
-    "directory": "layer"
+    "url": "git+https://github.com/lupinum-dev/ginko.git",
+    "directory": "packages/ginko-docs"
+  },
+  "homepage": "https://github.com/lupinum-dev/ginko/tree/main/packages/ginko-docs#readme",
+  "bugs": {
+    "url": "https://github.com/lupinum-dev/ginko/issues"
   },
-  "bin": {
-    "ginko-docs-favicons": "./runtime/generate-favicons.mjs"
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
   },
   "files": [
+    "nuxt.config.ts",
     "app",
-    "i18n",
-    "modules",
-    "public",
-    "runtime",
     "server",
     "shared",
-    "content-collections.ts",
-    "content.js",
-    "content.ts",
-    "components.ts",
-    "icon-bundle.ts",
-    "index.d.ts",
-    "nuxt.config.ts",
-    "tags.ts",
-    "!**/*.test.ts"
+    "icons",
+    "public",
+    "i18n",
+    "dist",
+    "CHANGELOG.md"
   ],
-  "type": "module",
   "main": "./nuxt.config.ts",
   "exports": {
     ".": "./nuxt.config.ts",
-    "./content": {
-      "types": "./content.ts",
-      "import": "./content.js",
-      "default": "./content.js"
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs"
     },
-    "./app-config": "./shared/types/app-config.ts",
-    "./components": "./components.ts",
-    "./nuxt-config": "./shared/types/nuxt-config.ts"
+    "./pages": "./dist/pages.mjs",
+    "./icons": "./dist/icons.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@iconify-json/circle-flags": "^1.2.10",
-    "@iconify-json/logos": "^1.2.12",
-    "@iconify-json/lucide": "^1.2.123",
-    "@nuxt/fonts": "^0.14.0",
-    "@nuxt/icon": "^2.5.0",
-    "@nuxt/image": "^2.1.0",
-    "@nuxt/kit": "^4.5.2",
-    "@nuxt/scripts": "^1.3.3",
-    "@nuxtjs/color-mode": "^4.0.1",
-    "@nuxtjs/i18n": "^10.6.0",
-    "@nuxtjs/mcp-toolkit": "0.18.1",
-    "@nuxtjs/robots": "^6.1.4",
-    "@nuxtjs/sitemap": "^8.3.4",
-    "@resvg/resvg-js": "^2.6.2",
-    "@shikijs/transformers": "^4.4.3",
-    "@tailwindcss/vite": "^4.3.3",
-    "@vueuse/core": "^14.4.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "h3": "1.15.11",
-    "motion-v": "^2.3.0",
-    "nitropack": "^2.13.4",
-    "nuxt-og-image": "^6.7.8",
-    "reka-ui": "^2.10.3",
-    "satori": "^0.19.3",
-    "sharp": "^0.35.3",
-    "shiki": "^4.4.3",
-    "tailwind-merge": "^3.6.0",
-    "tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
-    "zod": "4.4.3"
+    "@comark/vue": "0.7.0",
+    "@iconify-json/lucide": "^1.2.137",
+    "@iconify/utils": "^3.1.7",
+    "@lupinum/ginko-components": "^0.5.0",
+    "@nuxt/kit": "^4.6.0",
+    "beautiful-mermaid": "^1.1.3",
+    "katex": "^0.18.11"
   },
   "peerDependencies": {
-    "@lupinum/ginko-content": ">=1.0.0-beta.5 <2.0.0",
-    "nuxt": ">=4.5.1 <5",
-    "vue": "^3.5.40",
-    "vue-router": "^5.1.0"
+    "@lupinum/ginko": "^0.5.0",
+    "@lupinum/ginko-content": "^0.5.0",
+    "@lupinum/ginko-i18n": "^0.5.0",
+    "nuxt": "^4.6.0 || ^5.0.0-0",
+    "vue": "^3.5.0"
   },
-  "engines": {
-    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
+  "devDependencies": {
+    "@lupinum/ginko": "0.5.0",
+    "@lupinum/ginko-content": "0.5.0",
+    "@lupinum/ginko-i18n": "0.5.0",
+    "nuxt": "4.6.0",
+    "unbuild": "3.6.1",
+    "vue": "3.5.43"
   },
-  "scripts": {}
+  "scripts": {
+    "build": "unbuild"
+  }
 }

package/public/_docs/fonts/LICENSE

@@ -0,0 +1,188 @@
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter) Inter-Italic[opsz,wght].ttf: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+---- JetBrains Mono ----
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono) JetBrainsMono-Italic[wght].ttf: Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/server/feeds/blog-locale.get.ts

@@ -0,0 +1,9 @@
+// The feed of another language: /<locale>/blog/rss.xml. The main language has none here (404), its feed has no prefix.
+// Registered by modules/pages.ts only when the site has `posts`.
+import { createError, defineEventHandler, getRouterParam, useRuntimeConfig } from 'nuxt/server'
+import { serveBlogFeed } from '../lib/blogFeed'
+export default defineEventHandler((event) => {
+  const locale = getRouterParam(event, 'locale') ?? ''
+  if (locale === (useRuntimeConfig().public.ginko as { mainLocale: string }).mainLocale) throw createError({ statusCode: 404, statusMessage: 'Not found' })
+  return serveBlogFeed(event, locale)
+})

package/server/feeds/blog.get.ts

@@ -0,0 +1,4 @@
+// The feed of the main language: /blog/rss.xml. Registered by modules/pages.ts only when the site has `posts`.
+import { defineEventHandler, useRuntimeConfig } from 'nuxt/server'
+import { serveBlogFeed } from '../lib/blogFeed'
+export default defineEventHandler((event) => serveBlogFeed(event, (useRuntimeConfig().public.ginko as { mainLocale: string }).mainLocale))

package/server/lib/blogFeed.ts

@@ -0,0 +1,35 @@
+// The blog feed of one language, read from the build-time file bundle (what /__ginko/files/<locale>.json serves).
+// Only file blogs have a feed: posts that live on the platform are not in that bundle.
+import { createError, useRuntimeConfig, type RequestEvent } from 'nuxt/server'
+import schema from '#ginko/schema'
+import fileBundles from '#ginko/files'
+import locales from '#ginko/locales'
+import type { Brick } from '@lupinum/ginko'
+import { isVisible, todayIn } from '@lupinum/ginko/internal'
+import { rssXml } from '@lupinum/ginko/basics'
+
+export function serveBlogFeed(event: RequestEvent, locale: string) {
+  const config = useRuntimeConfig().public.ginko as { name: string; url: string; locales: string[]; timeZone: string; seo: { description?: string } }
+  const bundle = config.locales.includes(locale) ? fileBundles[locale as keyof typeof fileBundles] : undefined
+  const posts = bundle?.bricks.posts
+  const def = schema.bricks.posts as Brick | undefined
+  if (!bundle || posts?.kind !== 'collection' || def?.kind !== 'collection') throw createError({ statusCode: 404, statusMessage: 'No blog' })
+
+  const base = config.url.replace(/\/$/, '')
+  const authors = bundle.bricks.authors?.kind === 'collection' ? bundle.bricks.authors.items : []
+  const today = todayIn(config.timeZone)
+  const route = def.route?.[locale as keyof typeof def.route]
+  if (!route) throw createError({ statusCode: 404, statusMessage: 'No blog' })
+  const items = posts.items.filter((p) => p.urls?.[bundle.locale] && isVisible(def, p.data, today)).map((p) => ({
+    title: String(p.data.title),
+    link: base + p.urls![bundle.locale],
+    description: typeof p.data.description === 'string' ? p.data.description : undefined,
+    date: String(p.data.date),
+    authors: ((p.data.authors as string[] | undefined) ?? []).flatMap((id) => authors.find((a) => a.id === id)?.data.name ?? []).map(String),
+  }))
+  const page = base + route.replace('/[slug]', '')
+  // RSS <language> is the BCP 47 tag of the locale (`languages` in the config), like the page head.
+  const language = locales.locales.find((l) => l.code === locale)?.language ?? locale
+  event.res.headers.set('content-type', 'application/rss+xml; charset=utf-8')
+  return rssXml({ title: `${config.name} Blog`, link: page, self: `${page}/rss.xml`, description: config.seo.description ?? `${config.name} Blog`, language, items })
+}

package/server/mcp/handler.ts

@@ -0,0 +1,108 @@
+// Read-only MCP server for the docs, minimal MCP Streamable HTTP: one JSON-RPC request in, one JSON response out.
+// Methods: initialize, ping, tools/list, tools/call (search_docs, read_doc). No sessions, no streaming, no auth:
+// it only returns what the public site already shows. Pure (the data comes in through `deps`), so tests call it directly.
+
+export interface DocsMcpHit { title: string, heading?: string, url: string, excerpt: string }
+export interface DocsMcpDeps {
+  search: (query: string, locale?: string) => DocsMcpHit[] | Promise<DocsMcpHit[]>
+  /** Markdown of the page at `path`, or undefined when there is none. */
+  read: (path: string) => string | undefined | Promise<string | undefined>
+}
+
+const PROTOCOL = '2025-03-26'
+const TOOLS = [
+  {
+    name: 'search_docs',
+    description: 'Search the documentation. Returns the best matching pages and sections with their path and an excerpt.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string' }, locale: { type: 'string', description: 'Language code, e.g. "en". Default: the main language.' } }, required: ['query'] },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'read_doc',
+    description: 'Read one documentation page as Markdown. `path` is the page path from search_docs, e.g. "/en/docs/languages".',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    annotations: { readOnlyHint: true },
+  },
+]
+
+type Json = Record<string, unknown>
+const ok = (id: unknown, result: unknown) => ({ jsonrpc: '2.0', id, result })
+const fail = (id: unknown, code: number, message: string) => ({ jsonrpc: '2.0', id: id ?? null, error: { code, message } })
+const text = (value: string, isError = false) => ({ content: [{ type: 'text', text: value }], ...(isError ? { isError: true } : {}) })
+
+async function callTool(params: Json, deps: DocsMcpDeps) {
+  const args = (params.arguments ?? {}) as Json
+  if (params.name === 'search_docs') {
+    if (typeof args.query !== 'string' || !args.query.trim()) return text('`query` must be a non-empty string.', true)
+    const hits = await deps.search(args.query, typeof args.locale === 'string' ? args.locale : undefined)
+    return text(hits.length
+      ? hits.map((h) => `- ${h.heading ? `${h.title} > ${h.heading}` : h.title}: ${h.url}${h.excerpt ? `\n  ${h.excerpt}` : ''}`).join('\n')
+      : 'No results.')
+  }
+  if (params.name === 'read_doc') {
+    // A page path of this site only: starts with "/", no scheme-relative "//", no "..", and no query or fragment,
+    // which would reach other routes (`/__ginko/search/en.json?`) through the `.md` lookup.
+    if (typeof args.path !== 'string' || !/^\/(?!\/)[^?#]*$/.test(args.path) || args.path.split('/').includes('..')) return text('`path` must be a page path like "/en/docs/languages".', true)
+    const markdown = await deps.read(args.path.replace(/\.md$/, ''))
+    return markdown === undefined ? text(`No page at ${args.path}.`, true) : text(markdown)
+  }
+  return undefined
+}
+
+/** One JSON-RPC message. `undefined` means "no response" (a notification). */
+export async function handleMcpMessage(message: unknown, deps: DocsMcpDeps): Promise<Json | undefined> {
+  if (typeof message !== 'object' || message === null || Array.isArray(message)) return fail(null, -32600, 'Invalid request')
+  const { id, method, params } = message as { id?: unknown, method?: unknown, params?: Json }
+  if (typeof method !== 'string') return fail(id, -32600, 'Invalid request')
+  if (id === undefined) return undefined // notifications such as notifications/initialized
+  switch (method) {
+    case 'initialize':
+      return ok(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'ginko-docs', version: '1' } })
+    case 'ping':
+      return ok(id, {})
+    case 'tools/list':
+      return ok(id, { tools: TOOLS })
+    case 'tools/call': {
+      const result = await callTool(params ?? {}, deps)
+      return result === undefined ? fail(id, -32602, `Unknown tool: ${String(params?.name)}`) : ok(id, result)
+    }
+    default:
+      return fail(id, -32601, `Method not found: ${method}`)
+  }
+}
+
+/** Messages in one batch; a client needs a handful, more only multiplies the work of one request. */
+export const MAX_BATCH = 20
+
+/** A request body: one message, or a batch of up to MAX_BATCH. */
+export async function handleMcp(body: unknown, deps: DocsMcpDeps): Promise<Json | Json[] | undefined> {
+  if (!Array.isArray(body)) return handleMcpMessage(body, deps)
+  if (body.length === 0 || body.length > MAX_BATCH) return fail(null, -32600, `Invalid request: a batch holds 1 to ${MAX_BATCH} messages`)
+  const out = (await Promise.all(body.map((m) => handleMcpMessage(m, deps)))).filter((r): r is Json => r !== undefined)
+  return out.length ? out : undefined
+}
+
+/** Largest request body the endpoint reads (1 MB); a JSON-RPC call is a few hundred bytes. */
+export const MAX_BODY_BYTES = 1_000_000
+
+/**
+ * The body text of `request`, or undefined when it is over `max` bytes. A `content-length` over the limit is
+ * refused without reading anything; without one (chunked upload) the stream is cut as soon as it passes the limit.
+ */
+export async function readLimitedText(request: Request, max = MAX_BODY_BYTES): Promise<string | undefined> {
+  const declared = Number(request.headers.get('content-length'))
+  if (Number.isFinite(declared) && declared > max) return undefined
+  if (!request.body) return ''
+  const reader = request.body.getReader()
+  const decoder = new TextDecoder()
+  let size = 0
+  let result = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) { await reader.cancel(); return undefined }
+    result += decoder.decode(value, { stream: true })
+  }
+  return result + decoder.decode()
+}

package/server/routes/__ginko/docs-mcp.ts

@@ -0,0 +1,35 @@
+// `POST /__ginko/docs-mcp`: read-only MCP endpoint of the docs (see ../../mcp/handler.ts). It lives under `/__ginko/`
+// like the other generated endpoints, so it cannot collide with a page or with the platform's own `/mcp`.
+import { createError, defineEventHandler, serverFetch, setResponseStatus } from 'nuxt/server'
+import indexes from '#ginko/search'
+import locales from '#ginko/locales'
+import { loadIndex, search, type SearchIndex } from '@lupinum/ginko/search'
+import { handleMcp, readLimitedText } from '../../mcp/handler'
+
+// The loading index per locale, kept as its promise so two first requests share one load.
+const loaded = new Map<string, Promise<SearchIndex>>()
+
+export default defineEventHandler(async (event) => {
+  if (event.req.method !== 'POST') throw createError({ statusCode: 405, statusMessage: 'POST only' })
+  // Over 1 MB: refuse before parsing (a plain Node host has no body limit of its own).
+  const raw = await readLimitedText(event.req)
+  if (raw === undefined) throw createError({ statusCode: 413, statusMessage: 'Request body too large (limit 1 MB)' })
+  let body: unknown
+  try { body = raw === '' ? undefined : JSON.parse(raw) } catch { throw createError({ statusCode: 400, statusMessage: 'Body must be JSON' }) }
+  const response = await handleMcp(body, {
+    async search(query, locale = locales.defaultLocale) {
+      const json = Object.hasOwn(indexes, locale) ? indexes[locale as keyof typeof indexes] : undefined
+      if (!json) return []
+      let index = loaded.get(locale)
+      if (!index) loaded.set(locale, index = loadIndex(json))
+      return search(await index, query, { limit: 8 })
+    },
+    // The same Markdown the public `<page>.md` twin returns: ask the site's own middleware, in-process (Nuxt 4.6 and 5).
+    async read(path) {
+      const response = await serverFetch(event, `${path === '/' ? '/index' : path.replace(/\/+$/, '')}.md`, { forwardHeaders: false }).catch(() => undefined)
+      return response?.ok ? response.text() : undefined
+    },
+  })
+  if (response === undefined) { setResponseStatus(event, 202); return '' }
+  return response
+})

package/shared/layerRoutes.ts

@@ -0,0 +1,66 @@
+// Which pages and feeds the layer adds for a site, decided from the site's Ginko config and the paths its own pages
+// already take. Pure, so modules/pages.ts only wires the result into Nuxt and the test can check every case.
+export interface SiteOptions { locales?: readonly string[], pages?: Record<string, Record<string, string> | undefined>, bricks?: Record<string, { route?: Record<string, string> } | undefined> }
+
+export interface LayerPage { name: string, path: string, /** In `app/docs-pages/`. */ file: string }
+
+export interface LayerRoutes {
+  docs: { base: string }
+  /** Where the bricks put the blog list and the changelog (main language), whoever serves them. The app links here. */
+  addresses: { blog?: string, changelog?: string }
+  /** The pages the layer adds: each only where the site has no page of its own. */
+  pages: LayerPage[]
+  /** The blog and changelog the layer serves itself. Feeds are `<blog>/rss.xml` and `/:locale<blog>/rss.xml`. */
+  blog?: string
+  changelog?: string
+  /** A brick is configured but has no address to put a page at (the changelog brick without a route or `pages.changelog`). */
+  noAddress: string[]
+}
+
+/** The brick's address in the main language, with `[slug]` as `:slug()`; the list page is the parent path. */
+function listPath(route: string | undefined): string | undefined {
+  if (!route) return undefined
+  const list = route.replace(/\/\[slug\]$/, '')
+  return list.includes('[') ? undefined : list || '/'
+}
+
+/** A page as Nuxt has it once every `pages:extend` ran: its scanned path and, from the templates' page-paths module, its addresses per language. */
+export interface PageLike { path: string, meta?: { i18n?: false | { paths?: Record<string, string> } } | undefined }
+
+/** The addresses a page answers at in the main language: its path and `meta.i18n.paths[main]` when set (`/news` answers at `/blog`). */
+function addressesOf(page: PageLike, main: string): string[] {
+  const mapped = page.meta?.i18n && page.meta.i18n.paths?.[main]
+  return mapped ? [page.path, mapped] : [page.path]
+}
+
+export function layerRoutes(site: SiteOptions | undefined, pages: Iterable<PageLike>): LayerRoutes {
+  const bricks = site?.bricks ?? {}
+  const main = site?.locales?.[0] ?? ''
+  const taken = new Set<string>()
+  for (const page of pages) for (const path of addressesOf(page, main)) taken.add(path)
+  // docsCollection writes `<base>/[slug]` for the main language; other languages get a prefix from ginko-i18n.
+  const docsBase = bricks.docs?.route?.[main]?.replace(/\/\[slug\]$/, '') ?? '/docs'
+  const blog = bricks.posts ? listPath(bricks.posts.route?.[main]) : undefined
+  // The changelog has no page of its own per entry: its list lives at the route the brick has, else at `pages.changelog`.
+  const changelog = bricks.changelog ? listPath(bricks.changelog.route?.[main]) ?? site?.pages?.changelog?.[main] : undefined
+  const free = (path: string | undefined) => (path && !taken.has(path) ? path : undefined)
+  const noAddress = [...(bricks.posts && !blog ? ['posts'] : []), ...(bricks.changelog && !changelog ? ['changelog'] : [])]
+  const addedBlog = free(blog)
+  const addedChangelog = free(changelog)
+  const wanted: Array<LayerPage | undefined> = [
+    { name: 'docs-slug', path: `${docsBase}/:slug()`, file: 'doc.vue' },
+    { name: 'docs', path: docsBase, file: 'docs.vue' },
+    { name: 'index', path: '/', file: 'index.vue' },
+    addedBlog ? { name: 'blog', path: addedBlog, file: 'blog.vue' } : undefined,
+    addedBlog ? { name: 'blog-slug', path: `${addedBlog}/:slug()`, file: 'post.vue' } : undefined,
+    addedChangelog ? { name: 'changelog', path: addedChangelog, file: 'changelog.vue' } : undefined,
+  ]
+  return {
+    docs: { base: docsBase },
+    addresses: { ...(blog && { blog }), ...(changelog && { changelog }) },
+    pages: wanted.filter((page): page is LayerPage => !!page && !taken.has(page.path)),
+    ...(addedBlog && { blog: addedBlog }),
+    ...(addedChangelog && { changelog: addedChangelog }),
+    noAddress,
+  }
+}

package/shared/paths.ts

@@ -0,0 +1,4 @@
+// The layer's fixed addresses, shared by the bricks (src/config.ts), the page module and the app. Internal: not
+// exported from `@lupinum/ginko-docs/config`, so the paths can gain a `base` option later without a breaking change.
+export const BLOG_PATH = '/blog'
+export const CHANGELOG_PATH = '/changelog'