docs: improve agent-friendly docs score (AFDocs quick wins)

[rachaelrenk]

Summary

Addresses failing AFDocs scorecard checks to improve the agent-friendly docs score from 82/100 (B) toward 95+ (A).

Changes

Task 1: llms.txt directive on all pages

• HTML: Added a visually-hidden div in CustomHeader.astro with a link to /llms.txt and a note about .md URL availability.
• Markdown: Modified docs-markdown-integration.js to prepend a blockquote directive to every generated .md file.

Task 2: Content negotiation middleware

• New src/middleware.ts -- Astro middleware that rewrites requests to the .md variant when agents send Accept: text/markdown or are identified by user-agent. Uses the existing shouldServeMarkdown() helper from src/lib/docs-markdown.js.

Task 3: Content-start-position verification

• Verified the link rel alternate type text/markdown already appears early in head -- no repositioning needed. Tasks 1+2 are the primary mitigations.

Task 4: llms.txt coverage improvement

• Fixed university/** to guides/** in the starlightLlmsTxt customSets config (directory was renamed but config was not updated).
• Added community pages (contributing, open-source-partnership, refer-a-friend) to the Support customSet.
• Corrected the exclude config comment to clarify it only applies to llms-small.txt, not llms-full.txt.

Task 7: MCP discovery file

• Added public/.well-known/mcp.json pointing to the existing Kapa MCP at https://warp.mcp.kapa.ai/sse. Team consensus (Petra, Ben, Hong Yi) was that a custom MCP server is not needed -- Warp has built-in product knowledge, and this check is primarily a Mintlify upsell.

AFDocs checks addressed

Check	Before	After
llms-txt-directive-html	FAIL	PASS
llms-txt-directive-md	FAIL	PASS
content-negotiation	FAIL	PASS
content-start-position	FAIL	Mitigated
llms-txt-coverage	80%	Improved
MCP Server Discoverable	FAIL	PASS

References

• AFDocs Remediation Plan
• Oz conversation

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 5, 2026 10:25pm

[hongyi-chen]

What do we have to do to get this to work? Going to the URL gives me a 404. cc @dannyneira

[rachaelrenk]

Good catch @hongyi-chen, the /sse path was wrong, fixed in d93f0a1 (base URL is just https://warp.mcp.kapa.ai).

Browsing directly will still return a 401 — that's expected. The Kapa MCP server uses OAuth authentication, so only MCP clients that handle the OAuth flow can connect (e.g., Claude, Cursor). The .well-known/mcp.json file is a discovery endpoint that tells those clients where to connect, not a human-facing URL.