Publish a capability index agents can find

Provide a root-level, machine-readable index of what an agent can do, with metadata on every resource.

Why

Agents discover features through structured indexes, not visual menus. The canonical AX framework (agentexperience.ax — Agent Accessibility) states that agents must have a clear path to capability discovery without relying on visual UX. The Google A2A protocol formalizes this with Agent Cards at /.well-known/agent.json, now in production at 150+ organisations. The llms.txt standard provides a complementary content-level index.

Do

Serve a /.well-known capability manifest.

Don't

Hide capabilities behind JS navigation.

Artifact

Serve at /.well-known/agent-capabilities.json:

{
  "name": "Acme",
  "description": "Acme helps teams do X.",
  "auth": { "type": "bearer", "scopes_url": "/docs/scopes.md" },
  "actions": [
    { "name": "search_orders", "method": "GET", "path": "/v1/orders",
      "scopes": ["orders:read"], "description": "Find a customer's orders by email or order ID." },
    { "name": "create_refund", "method": "POST", "path": "/v1/refunds",
      "scopes": ["refunds:write"], "consequential": true,
      "description": "Issue a refund. Irreversible. Supports dry_run." }
  ],
  "docs": "/llms.txt"
}