feat: migrate to nuxt-agent-discovery

[benjamincanac]

Replaces the hand-rolled markdown negotiation and agent discovery layer with nuxt-agent-discovery 0.5.0, the same shape as nuxt/ui#6883, nuxt/nuxt.com#2407 and nuxt-content/docus#1435. @nuxtjs/robots and @nuxtjs/sitemap were already in the layer, so the module hooks into both: agent Allow groups and Content-Signal through robots:config, raw twins filtered out of sitemap.xml.

Deleted

• modules/markdown-rewrite.ts, utils/markdown-rewrite.ts and their test: the Vercel 307 routes now come from the module's vercel preset
• server/routes/raw/[...slug].md.get.ts, server/utils/markdown.ts, server/utils/not-found.ts: the raw route, the markdown pipeline and the markdown 404 body
• modules/skills/: the skills scanner and the /.well-known/skills/ routes
• most of server/plugins/llms.ts: link rewriting to raw twins, the llms-full.txt builder and the prerender hints

Configuration

agentDiscovery in the layer's nuxt.config.ts: a createComarkSource() adapter over getProdContent(), excludePrefixes for /tree, /blob, /pr and /logos, and the discovery links for /openapi.json and the RSS feed. modules/config.ts seeds what only the layer knows, like docus does: the MCP server card from the mcp-toolkit options, and comarkDocs.skills forwarded to agentDiscovery.skills as a deprecated alias with a warning. It also adds /sitemap.md to the ISR rules and the webhook purge list.

One thing worth knowing for review: Nuxt queues a layer's modules array before its auto-scanned modules/ dir, so until now modules/config.ts ran after every module in the array and could not seed options a module reads at setup (the existing mcp seeding was affected too). The layer's own modules are now listed first in nuxt.config.ts, with their .ts extension, which is what makes the scan dedupe them instead of installing them a second time.

Kept in the layer

• modules/runtime/server/plugins/llms.ts: the llms.txt sections built from the content navigation, plus docs.llms.links. Registered from config.ts so it runs ahead of the module's bridge, which rewrites the page links to raw twins and renders llms-full.txt from the same adapter.
• The MCP tools and the assistant's get_page read through getAgentDocument() / listAgentPages(), so they return the same bytes as /raw/**. get-page gained a sections argument.

New

• /openapi.json (prerendered): the discovery layer from agentDiscoveryOpenApi(), advertised in the Link header and the api-catalog, versioned from the app's package.json
• @nuxtjs/sitemap runs with excludeAppSources: true, so server/api/__sitemap__/urls.get.ts is the only source and the prerendered skill files stay out
• the "Copy as markdown" link reads the module's rawPrefix instead of hardcoding /raw

What changes for agents

• Negotiation matches Accept: text/markdown, .md twin URLs and the 26 agent user agents from ai.robots.txt (it was Accept and curl/* before), and it works in dev
• / answers the landing page as markdown with a "Resources for Agents" block instead of redirecting to /llms.txt
• Vary: Accept, User-Agent on both halves of every page, a discovery Link header on /, canonical/alternate Link on the twins
• Every error gets a markdown body with the discovery links, not only raw 404s
• New documents: /openapi.json, /sitemap.md, /.well-known/api-catalog, /.well-known/mcp/server-card.json, agent groups and Content-Signal in robots.txt
• Raw documents open with title, description and canonical_url frontmatter and every link is absolute. Components render as HTML tags (markdown/html) instead of comark syntax
• llms-full.txt now includes the landing page

Breaking

comarkDocs.skills.dir still works but warns, use agentDiscovery.skills.dir. nitro.experimental.asyncContext is now on, the MCP tools reach the request through useEvent().

Checks

pnpm lint, pnpm test, pnpm typecheck and NITRO_PRESET=vercel pnpm build pass locally (openapi.json and the 5 skill files prerendered, 24 redirects and 2 rewrites injected). Every probe from the migration skill was run against pnpm dev: page negotiation, Vary and Link, the resources block on /, sitemap.md, sitemap.xml, the api-catalog, the server card, openapi.json, skills, section redirects, markdown 404s, excluded previews, llms.txt ordering and both MCP tools. The preview (https://comark-docs-layer-qnm7ic5yd-nuxtlabs.vercel.app) is behind Vercel SSO, so the deployed-site checks (Vary and Link off the CDN, the edge rewrites and redirects) still have to run with a protection bypass token.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
comark-docs-layer	Ready	Preview	Sep 5, 2026 11:55am UTC

[coldtea-pr-lens]

◈ PR Lens

🟢 +2 new · 🟠 ~6 changed · 🔴 -3 removed · 2 flows · 23 files · commit 1f302c2

Architecture

11 components touched across 6 lanes.

Open full size

Inside the changed components — 2 views

Component view — Agent Discovery Pipeline

Consolidates markdown negotiation, raw mirrors, skills catalog, and OpenAPI spec generation into nuxt-agent-discovery, replacing custom handlers.

Component view — MCP & Assistant Tooling

Refactors the assistant endpoint and MCP tools (get-page, list-pages) to use getAgentDocument and listAgentPages from nuxt-agent-discovery.

Data flow

Agent content negotiation and markdown fetch · MCP documentation lookup via get-page

Open full size

The other flows — 1 sequence

MCP documentation lookup via get-page

Drill down

Client ＆ Browser — 1 component

🟡 CHANGED App Shell ＆ Layouts

Documentation layout and navigation UI, updated to resolve markdown mirror links from agentDiscovery runtime config.

• app/components/docs/DocsPageAsideLinks.vue:13-18
• app/components/layouts/LayoutsDocs.vue
• app/app.vue

Edge ＆ Routing — 2 components

🟡 CHANGED Edge ISR Cache

Vercel edge cache serving HTML pages, raw markdown mirrors, and agent discovery documents including /sitemap.md.

• modules/config.ts:184-204

🔴 REMOVED Markdown Content Negotiator

Custom Vercel build-output redirect injector for Accept: text/markdown and curl requests, replaced by nuxt-agent-discovery.

• modules/markdown-rewrite.ts
• utils/markdown-rewrite.ts

Server Routes ＆ APIs — 8 components

🟢 NEW Agent Discovery Engine

Provides content negotiation, /raw/** mirrors, agent skills catalog, sitemap.md, and document resolution via comark adapter.

• nuxt.config.ts:27-44
• modules/config.ts:159-182
• server/utils/agent-source.ts:1-8

🟢 NEW OpenAPI Discovery Route

Serves the OpenAPI 3.1.0 specification generated from agent-discovery route configuration.

• server/routes/openapi.json.get.ts:1-24

🔴 REMOVED Raw Markdown Route

Custom /raw/** markdown mirror route and 404 response generator, removed in favor of nuxt-agent-discovery.

• server/routes/raw/[...slug].md.get.ts
• server/utils/markdown.ts
• server/utils/not-found.ts

🔴 REMOVED Skills Module

Custom build-time scanner and nitro route handlers for Agent Skills at /.well-known/skills/, replaced by nuxt-agent-discovery.

• modules/skills/index.ts
• modules/skills/utils/index.ts
• modules/skills/runtime/server/routes/skills-files.ts

🟡 CHANGED Sitemap, RSS ＆ LLMs Feeds

Generates XML sitemaps, RSS feed, and llms.txt navigation sections via nitro hooks ahead of the agent discovery bridge.

• server/api/__sitemap__/urls.get.ts
• server/routes/rss.xml.get.ts
• modules/runtime/server/plugins/llms.ts:1-74

🟡 CHANGED Revalidate Webhook

GitHub push webhook purging changed page HTML, raw mirrors, llms indexes, and sitemap.md from edge ISR.

• server/api/revalidate.post.ts:150-165

🟡 CHANGED Assistant Stream API

AI assistant streaming endpoint querying getAgentDocument during tool execution instead of custom markdown renderers.

• server/api/assistant.post.ts:95-105

🟡 CHANGED MCP Server

MCP tools (get-page, list-pages) refactored to consume getAgentDocument and listAgentPages with section filtering.

• server/mcp/tools/get-page.ts:1-33
• server/mcp/tools/list-pages.ts:1-20
• server/mcp/tools/search-docs.ts

View

• Architecture lens
• Data flow lens
• Expand every detail
• Show unchanged neighbours

Tip

Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.

🪧 More tips

• Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.
• Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.
• GitHub will not let you zoom an image in a comment. The link under each diagram opens it full size on a page of its own, where you can.
• The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
• Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.
• PR Lens is free for open source. A star on the repository is what keeps it going.
• Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
• The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

---

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Come say hi on Discord

[github-actions]

Documentation previews

📚 Preview all documentation changes (follows new pushes)

• /getting-started/configuration
• /concepts/architecture
• /deployment/vercel

Pinned to the current head: 1f302c2

[pkg-pr-new]

npm i https://pkg.pr.new/comarkdown/comark-docs@40

commit: 1f302c2