Skip to content
· 6 min LIVE

An Agent Lands on Your Homepage — What Can It Actually Read?

Eleven machine-readable manifests under /.well-known plus a generated llms.txt — the full AgentBadge discovery surface is built from live sources (openapi, route config, SKU catalog), never hand-edited, CI-gated on drift, and dogfooded by our own 142-rule readiness scanner.

AB
AgentBadge Team
Agency for the Agentic Web
An Agent Lands on Your Homepage — What Can It Actually Read?
🤖 For AI agents: Machine-readable: JSON Markdown llms.txt Agent Guide

An AI agent that lands on agentbadge.xyz now finds eleven live .well-known manifests (agent-card, api-catalog, ERC-8004, MCP server card, evaluation ladder, DID/JWKS, security.txt) plus a generated llms.txt — all projected from live code sources, CI-checked for drift, and verified by our own scanner at 100% pass.

An AI agent evaluating a vendor does what a human does: it opens the site and looks for proof. The difference is speed and format — the agent gives you seconds, not minutes, and it wants JSON, not hero banners. Until recently, an agent landing on agentbadge.xyz found a page built for humans and nothing else — while our own readiness scanner was out there grading other sites on exactly the signals we lacked. The cobbler had no shoes. This week we fixed that: the entire discovery surface is now generated from live sources, served free with no auth, and verified by our own scanner in CI.

This is article C14 in the Arc Campaign series. It sits directly under C15 — C14 is how an agent finds us; C15 is what it reads once it wants to buy.

An agent arriving at a site that opens into a machine-readable JSON interior

What does an agent find in 200 milliseconds?

Eleven machine-readable manifests, all 200 OK, all free, all generated — not hand-maintained:

/.well-known/agent-card.json        A2A v1.0 — who we are, skills[]
/.well-known/api-catalog            RFC 9727 linkset — every API entry
/.well-known/erc8004-agent.json     on-chain identity registration
/.well-known/mcp/server-card.json   MCP capabilities + tools surface
/.well-known/agent-evaluation.json  verification ladder (claims→refs)
/.well-known/owner-questions.json   "who runs this" for due-diligence
/.well-known/did.json               did:web:agentbadge.xyz document
/.well-known/did-configuration.json signed domain linkage (VC-JWT)
/.well-known/jwks.json              real Ed25519 key, kid'd
/.well-known/security.txt           RFC 9116, Expires generated +1y
/llms.txt                           agent-oriented sitemap

The agent-card alone answers the A2A handshake: name, provider, supportedInterfaces[], skills[] with tags and examples, and securitySchemes declaring x402 as the payment rail. One GET and a foreign agent knows our identity, capabilities, and how to pay.

A glowing .well-known directory tree of eleven manifests, each marked 200 OK

Where do the manifests come from?

Not from a copywriter — from the code itself. A manifest registry collects the same live sources the runtime uses — openapi.ts, route config, blog-data.ts, the SKU catalog — and every manifest is a projection of that truth:

  • Boot-time: env-dependent manifests (URLs, keys, DID document) are generated into a manifest registry when the server starts — routes serve from it, so there is exactly one source.
  • Build-time: bun run gen:discovery writes snapshots under public/.well-known/ — manual edits are banned.
  • CI drift-check: regenerate and git diff --exit-code — if a manifest drifted from the code that produced it, the build fails. Env-dependent files get golden tests with mocked env instead.

This is the difference between us and a hand-maintained .well-known directory: ours cannot go stale without the build telling us.

Pipeline diagram: live sources → manifest registry → .well-known manifests → consumers, with a CI drift check

What does a machine-readable sitemap look like?

llms.txt — the de-facto convention for telling an LLM "start here": H1 title, a blockquote describing the platform, then ## sections of named links. Ours is generated with sections for machine-readable entry points, quick start, free and paid endpoints:

# AgentBadge

> Agent identity, discovery, and x402 micropayments on Arc.

## Machine-readable Entry Points
- [Agent Card JSON](/.well-known/agent-card.json) — capabilities
- [OpenAPI 3.1 Spec](/api/specs) — full API spec
- [MCP Server](/mcp) — JSON-RPC over HTTP
- [Service Catalog](/api/v1/services) — SKUs, prices, input schemas

A crawler following this file reaches every paid surface with its price and input schema — the llms.txt services section anchors into the same /api/v1/services catalog that powers the bazaar extension from C15.

Generation pipeline from live sources through the manifest registry to the .well-known outputs, guarded by a CI shield

Why serve the same page twice?

Because the reader might not be a browser. Accept: text/markdown on any page gets the markdown representation instead of HTML — verified live:

$ curl -sH "Accept: text/markdown" https://agentbadge.xyz/blog
content-type: text/markdown; charset=utf-8

Blog articles additionally carry .md mirrors — /blog/arc-c10-payer-binding.md returns 200 text/markdown. The HTML page stays canonical; <link rel="alternate" type="text/markdown"> points machines at the twin. One URL, two readers, zero content duplication.

One URL split into two representations — HTML page for a human reader, markdown document for an agent

Can an agent verify our claims without trusting us?

That is the point of agent-evaluation.json — a verification ladder: claims ordered by how long they take to check, each with an explicit action and ref:

{
  "depth": "5s",
  "checks": [
    { "claim": "mainnet deployment — AgentEventLog on Arc",
      "action": "open",
      "ref": "https://explorer.arc.io/address/0x1bb6…4700" },
    { "claim": "agent card published (A2A v1.0)",
      "action": "GET",
      "ref": "https://agentbadge.xyz/.well-known/agent-card.json" }
  ]
}

At 5 seconds an agent confirms we exist on-chain and publish a card. At 60 seconds it checks manifest validity, the live OpenAPI spec, and the refusal contract. Deeper rungs point at dogfood transactions and audit trails. owner-questions.json answers the due-diligence questions an enterprise agent would ask — operator, jurisdiction, contact — in the same machine-readable shape.

A verification ladder of three glowing steps labeled 5s, 60s, 5min, climbed by an agent

How do we know it works?

We run our own scanner on ourselves — the same 142-rule engine that grades other sites' agent-readiness. The rules it checks on foreign domains — /.well-known/mcp/server-card.json (AB-006), llms.txt (AB-014), JSON-LD/OG metadata (AB-015/016), ai.txt (AB-017) — now run against agentbadge.xyz in CI as a dogfood gate: 100% pass required. If a deploy breaks a manifest, our own product flags our own site.

Agent journey diagram: land on site → llms.txt → agent-card → api-catalog → evaluation ladder → free endpoint → 402 payment → paid response

Honest status

  • Live now: all 11 manifests 200 OK on agentbadge.xyz; markdown negotiation serving text/markdown; .md mirrors on blog articles; generated, not hand-edited.
  • Deliberately absent: ai-plugin.json — OpenAI killed ChatGPT Plugins in 2024; publishing a dead manifest is cargo cult, not compliance. /.well-known/agent.json returns 301 to agent-card.json instead of rotting as a stale v0.x file.
  • Identity: did:web:agentbadge.xyz resolves (see C27); Arc-era identities stay as ERC-8004 eip155: refs, not DIDs.
  • To verify right now: curl https://agentbadge.xyz/.well-known/agent-card.json — or point our scanner at us: npx agentbadge-scan agentbadge.xyz.

C14 in the Arc Campaign series. C15 continues the journey — the agent found us, now it reads the price list. Earlier: C27 made the domain itself the identity.