# Well-Known — make your site discoverable by agents

> A live workshop deck delivered at Vibe Coding Nights #35 on 2026-06-03 at Frontier Tower, San Francisco. Hand-rolls the five well-known files that make a site discoverable by AI agents (agent-card.json, mcp.json, ai-agent.json, oauth-protected-resource, llms.txt), deploys them to a Cloudflare Worker, and scores the domain with isitagentready.com before and after. This deck ships all five files itself.

## The thesis

The agentic web's discovery layer is almost empty. Cloudflare's April 2026 study found 3.9% of sites do markdown content negotiation and fewer than 15 publish an MCP Server Card. Five text files, none needing a framework, close most of the gap. This deck hand-writes them live.

## Site map

- `/` the deck (60 slides, deep-linkable via /#1 through /#60)
- `/.well-known/agent-card.json` A2A v1.0.0 agent card (this deck's own)
- `/.well-known/mcp.json` MCP discovery card
- `/.well-known/ai-agent.json` Aiia agent manifest
- `/.well-known/oauth-protected-resource` RFC 9728 auth metadata (demonstration)
- `/llms.txt` this file
- `/sitemap.xml` sitemap
- `/robots.txt` agent-aware crawl policy
- `/assets/og.svg` 1200x630 social card

## The five files

### /.well-known/agent-card.json
A2A v1.0.0 (Linux Foundation). The agent's business card. Minimum: name, description, url. Source: https://a2a-protocol.org/latest/

### /.well-known/mcp.json
MCP server discovery over HTTP (SEP-2127). Validated by Shopify and Smithery. Advertises transport, url, tools.

### /.well-known/ai-agent.json
Aiia working group spec. Required: name, description. Wired into Cloudflare's isitagentready scanner. Source: https://aiia.ro/spec/ai-agent-json/

### /.well-known/oauth-protected-resource
RFC 9728. The auth handshake target both MCP and A2A piggyback on. Says where to authenticate; it does not mint tokens.

### /llms.txt
Jeremy Howard's markdown sitemap. Top level, not under .well-known. Curate by hand. Source: https://llmstxt.org/

## The trap

llms.txt lives at /llms.txt (the site root). ai-agent.json lives under /.well-known/. Mixing them up is the most common mistake. Missing CORS (Access-Control-Allow-Origin) on /.well-known/* makes browser-side agents fail silently.

## Citation

Rayyan Zahid. Well-Known, make your site discoverable by agents. Vibe Coding Nights #35, Frontier Tower SF, 2026-06-03. https://vcn-35-well-known.vercel.app/

Licensed CC-BY-SA-4.0.