1029: Optimize Docs Agent Readiness

[saudsami]

Summary

Type of Change

• Documentation content
• Docs site behavior
• Navigation, routing, or metadata
• OpenAPI or generated reference
• Build, tooling, or CI

Verification

• bun run test
• bun run types:check
• bun run lint
• bun run build
• Checked affected pages locally

Screenshots

Notes for Reviewers

[github-actions]

Vercel Preview

Preview URL: https://docs-portal-h1i1zr5i4-agoraio.vercel.app

[saudsami]

Agent Readiness Score Summary Report

Fixed

• Link headers (RFC 8288) — service-doc, describedby, api-catalog relations on / and /en.
• Content Signals — Content-Signal: ai-train=yes, search=yes, ai-input=yes in robots.txt.
• API Catalog (RFC 9727) — /.well-known/api-catalog, generated from the real OPENAPI_LANES registry (7 APIs).
• MCP Server Card (SEP-2127) — /.well-known/mcp-server-card, spec-compliant shape alongside the existing Cloudflare-passing endpoints.

Won't fix

• OAuth/OIDC discovery metadata — every Agora API spec uses Basic Auth/API key, not OAuth; publishing this would fabricate a non-existent authorization server.
• OAuth Protected Resource metadata — same root cause; no real authorization_servers to list.
• auth.md — its own spec requires the two OAuth endpoints above, which don't apply here.
• Web Bot Auth (informational only) — identifies a site's outbound bot; docs-portal doesn't operate one.

Needs work outside this repo

DNS-AID (DNS for AI Discovery)

A DNS SVCB record that lets agents discover an organization's agent-facing endpoints (MCP, A2A, etc.) directly via DNS, without first loading the website. Cloudflare's scanner checks for it as a discovery channel independent of HTTP; it's currently entirely absent for agora.io.

• Drafted record (ready to hand off, not yet published):

  _index._agents.docs.agora.io. 3600 IN SVCB 1 mcp.agora.io. (
      alpn="mcp"
      port="443"
      well-known="/.well-known/mcp-server-card"
  )

• Blocker: publishing DNS records requires access to the agora.io DNS zone. Cloudflare's guidance also recommends DNSSEC-signing the zone so the record is verifiable; a separate, larger decision for whoever owns that zone.

WebMCP

• What it is: a browser API (navigator.modelContext / soon document.modelContext) that lets a page expose callable tools (search, copy-page, etc.) directly to an in-browser AI agent.

• Blocker: the spec is mid-migration (navigator→document.modelContext, with Chrome deprecating the old shape in Chrome 150) and only available via a Chrome Origin Trial (149–156), which requires registering docs.agora.io for a trial token through Google — an account-level action outside this repo. Firefox/Safari haven't committed to the standard at all.