Agent-readable pages

Public representations

/llms.txt lists public content and connection endpoints. /llms-full.txt includes the landing, legal text, static demo content and every developer page. Each developer page has a .md representation, including /docs.md, deep pages and changelog entries.

curl http://localhost:3005/docs/features/todo-imports.md
curl http://localhost:3005/llms.txt

Developer content is English only. The landing and legal Markdown exist once per language at the page's path: /index.md and /privacy.md are English, /de/privacy.md and /fr/privacy.md the others, and a legacy ?lang=de answers a 301 to the path form. Negotiating text/markdown on /de returns /de/index.md. Developer docs URLs enter the sitemap without hreflang alternates, with a <lastmod> from the frontmatter date or the git commit date. Robots permits docs and excludes authenticated routes.

Finding the Markdown

The Markdown copies are not in the sitemap; they are the same documents in another representation. Three paths lead to them:

/llms.txt lists every public page as its .md URL.
Every HTML page that has a copy carries <link rel="alternate" type="text/markdown" href="…">, and the Markdown answers with Link: <…>; rel="canonical"; type="text/html" back.
Content negotiation: a GET with text/markdown as the best-weighted Accept type (Accept: text/markdown, or above text/html) is answered with the Markdown copy and a Content-Location. A browser's text/html, …, */*;q=0.8 and a tie keep HTML. Every negotiable path sends Vary: Accept. The policy lives in apps/web/src/platform/seo/request-policy.ts and runs in server.ts around the framework handler.

curl -s -H 'Accept: text/markdown' http://localhost:3005/docs/features/agent-pages
curl -sI -H 'Accept: text/markdown' http://localhost:3005/ | grep -i 'content-type\|content-location\|vary'

Discovery from the origin

MCP clients that only know the origin probe /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server and /.well-known/openid-configuration. The Better Auth issuer is <origin>/api/auth, so each root form has a route under apps/web/src/routes/[.]well-known/ that forwards into auth.handler: the protected-resource document unchanged (the plugin matches the root and /api/mcp path forms itself), the two server documents rewritten to their issuer-relative URL. The JSON is always the plugin's own.

Responses from an origin other than VITE_SITE_URL carry X-Robots-Tag: noindex, so a preview deployment's llms.txt and pages never enter an index (SEO and discovery).

Build and rendering

Fumadocs MDX compiles the repository content and processed Markdown at build time. The headless core supplies the page tree and search. Articles render on the server with shared UI tokens; a public GET route supports browser navigation. Runtime code reads no documentation files from disk and does not evaluate MDX source.

The existing ADR files and docs/connect-your-agent.md are imported into the collection, not copied. Relative references become docs links or repository links during compilation. Shiki highlighting happens during the build with github-light/github-dark tokens.

Extend

Add MDX with a title and description under apps/web/content/docs, then place it in its folder's meta.json. Use ordinary Markdown headings and links. Add a diagram as an accessible static SVG, with its light/dark variants. The source/link tests, sitemap and llms generation pick up the page automatically.

These routes contain only curated public content. Never add private Threads, account data or Organization exports to the public collection. Tool authorization remains the responsibility of the authenticated API.