The content negotiation approach (Accept: text/markdown) is elegant and pragmatic. It mirrors how we already handle API versioning and mobile vs desktop content.

One thing I'd add from the agent-builder side: agent developers also need to think about how their agents present themselves to external services. Right now most agents hit websites as generic user-agents, and that's a missed opportunity. If agents identified themselves with structured capabilities (what formats they accept, what actions they can take, what permissions they have), services could tailor responses much more intelligently.

We're already seeing this with MCP -- the protocol gives agents a structured way to discover and invoke tools. But the content side is lagging behind. Your approach of treating documentation as a first-class agent interface closes that gap.

The point about models reading only the first N lines is underappreciated. I've seen agents fail not because the info wasn't there, but because it was buried 200 lines into a doc. Front-loading the most actionable content is basically SEO for agents.