# Agent Discovery Surface: .well-known Manifests + llms.txt

## Summary

agentbadge.xyz serves a fully generated machine-readable discovery
layer: 11 manifests under `/.well-known/` plus a generated
`llms.txt` sitemap. Nothing is hand-edited — every manifest is a
projection of live sources (openapi.ts, route config, blog-data.ts,
SKU catalog) built into a manifest registry at boot; CI fails on
drift (`git diff --exit-code` on regenerated snapshots, golden tests
for env-dependent manifests).

## Live Manifests (all 200 OK, no auth)

```
/.well-known/agent-card.json        A2A v1.0 — provider, skills[],
                                    supportedInterfaces[], x402
                                    securityScheme
/.well-known/api-catalog            RFC 9727 application/linkset+json
/.well-known/erc8004-agent.json     EIP-8004 registration-v1
/.well-known/mcp/server-card.json   MCP capabilities + tools
/.well-known/agent-evaluation.json  verification ladder (claims→refs)
/.well-known/owner-questions.json   operator/jurisdiction/contact
/.well-known/did.json               did:web:agentbadge.xyz document
/.well-known/did-configuration.json VC-JWT DomainLinkageCredential
                                    (EdDSA, iss==sub==DID, exp +1y)
/.well-known/jwks.json              Ed25519 key set (kid
                                    agentbadge-2026-1)
/.well-known/security.txt           RFC 9116, Expires generated +1y
/llms.txt, /llms-full.txt           llmstxt.org convention, generated
```

Legacy `/.well-known/agent.json` → `301` → `agent-card.json`.
`ai-plugin.json` is deliberately absent — ChatGPT Plugins EOL 2024.

## Generation Model

- `src/server/lib/agent-discovery/` — sources → manifests registry
- `src/server/routes/discovery.ts` — thin routes serving registry
- `bun run gen:discovery` — build-time snapshots under
  `public/.well-known/` + `public/llms*.txt`
- Boot-time: env-dependent manifests generate into the registry
  (one source of truth, zero drift); statics are snapshot files
- CI: regenerate + `git diff --exit-code` catches any drift

## Markdown Negotiation

`Accept: text/markdown` on any page → markdown representation.
Blog articles carry `.md` mirrors (`/blog/<slug>.md` → 200
`text/markdown`). Canonical page stays HTML; `<link
rel="alternate" type="text/markdown">` advertises the twin.

## Verification Ladder (agent-evaluation.json)

Claims ordered by check-cost, each `{claim, action, ref}`:
- `5s` — on-chain deployment (Arc explorer) + agent card
- `60s` — manifest validity, live OpenAPI, refusal contract
- deeper — dogfood transactions, audit trails

`owner-questions.json` answers enterprise due-diligence
(operator, jurisdiction, contact) in machine-readable form.

## Dogfood Gate

The 142-rule readiness scanner (agentbadge-scan) runs against
agentbadge.xyz itself in CI — AB-006 (mcp server-card), AB-014
(llms.txt), AB-015/016 (JSON-LD/OG), AB-017 (ai.txt). 100% pass
required; a broken manifest fails the deploy.

## Verify

```bash
curl -s https://agentbadge.xyz/.well-known/agent-card.json | jq
curl -sH "Accept: text/markdown" https://agentbadge.xyz/blog
npx agentbadge-scan agentbadge.xyz
```



    <section class="mt-8 rounded-xl border border-emerald-800/30 bg-slate-900/50 p-6">
      <h3 class="text-lg font-bold text-slate-100">Relevant Engineering Capabilities</h3>
      <p class="mt-1 text-sm text-slate-400">The AgentBadge team can help with what you're reading about.</p>
      <div class="mt-4 grid gap-3">
        
        <div class="rounded-lg border border-slate-700 bg-slate-800/50 p-4">
          <div class="flex items-center justify-between">
            <h4 class="text-sm font-semibold text-emerald-400">AI Agent Architecture</h4>
            <span class="text-xs text-slate-400">Confidence: 0.93</span>
          </div>
          <p class="mt-1 text-xs text-slate-400">Design and implementation of AI agent infrastructure, agent APIs, machine-readable interfaces, and agent tooling.
</p>
          <div class="mt-2 flex items-center gap-3 text-xs text-slate-500">
            <span>People: Paul</span>
            <span>Status: VERIFIED</span>
          </div>
        </div>
      </div>
      
        <div class="mt-3">
          <p class="text-xs text-slate-500 mb-1">Related services:</p>
          <div class="flex flex-wrap gap-2">
            <span class="text-xs rounded-full bg-slate-700 px-2 py-1 text-slate-300">AI Agent Consulting</span>
          </div>
        </div>
      <div class="mt-4">
        <a href="/agent-guide/team/capabilities" class="inline-flex items-center text-sm font-medium text-emerald-400 hover:text-emerald-300">
          View all capabilities →
        </a>
      </div>
    </section>