One URL Can Speak Human and Agent

Vercel is using plain old HTTP content negotiation to make documentation readable by both humans and agents. Same URL. Browser gets HTML. Agent sends Accept: text/markdown and gets Markdown.

That’s the clever bit: don’t invent a parallel docs universe if the protocol already has a slot for this. The Vercel guide shows a Next.js Route Handler for Markdown responses, then a next.config.ts rewrite that checks the Accept header and routes agent requests to the Markdown version.

The sitemap.md detail matters. A page-level Markdown response is useful, but an agent also needs a trailhead. Vercel’s documentation sitemap gives the model a crawlable map of the docs in the same format it can consume directly.

For joelclaw, this fits the agent-discovery work without adding bullshit ceremony. Keep canonical pages for people, serve Markdown projections for agents, and expose a sitemap.md so Pi, Codex, Claude, and whatever comes next can find the good stuff without scraping rendered UI.

Key Ideas

• HTTP content negotiation lets one URL return different formats based on the Accept header, so humans and agents don’t need separate documentation URLs.
• Next.js Route Handlers can return Content-Type: text/markdown directly when the source content already exists as Markdown.
• Next.js rewrites can inspect the Accept header and send text/markdown requests to a Markdown route while leaving normal HTML pages alone.
• A sitemap.md gives agents a crawlable documentation map, which is more useful than hoping they infer the site structure from navigation chrome.
• This pattern is a clean fit for agent discoverability: canonical human pages stay canonical, while agents get low-friction Markdown from the same surface.

Links

• How to serve documentation for agents
• Vercel documentation sitemap.md
• Vercel Docs
• Next.js Route Handlers
• Next.js rewrites
• MDN: HTTP content negotiation
• Anthony Shew on X
• Vercel on GitHub
• Pi