Domain live maps for web agents

Agents do not need another docs page. They need a tested map.

A human can visit a site, read marketing pages, click through docs, notice redirects, infer auth boundaries, and eventually understand what the company actually offers. Agents can do that too, but every agent repeating that crawl is slow, inconsistent, and sometimes unsafe.

The web already has useful files: robots.txt, sitemap.xml, llms.txt, OpenAPI, MCP manifests, A2A cards, OAuth metadata, and security contacts. There is not yet a common file that says: here is the current operational map, here is what we tested, here is what was stale or missing, and here is the safest first move for a bot.

wkdomains proposed convention

A domain live map is a dated JSON document that can be owner-published, registry-observed, or both. It should be treated like a health check for agent-readable web contracts, not a static directory listing. The map favors current evidence over permanent claims.

Live JSON samples

These are deliberately different recognizable domains. Some are agent-friendly, some hide the useful contract behind docs or GitHub, and most require a hard stop before authenticated, high-effect actions.

Draft JSON shape

The shape is intentionally review-oriented. It does not only list endpoints. It records the bot's understanding, discovery evidence, safe probes, auth boundary, policy constraints, owner questions, and freshness.

{
  "schema": "wkdomains.live-map.v0",
  "domain": "example.com",
  "observed_at": "2026-05-01T18:53:41Z",
  "observer": "wkdomains read-only sample scan",
  "confidence": "high",
  "freshness": {
    "status": "fresh",
    "checked_at": "2026-05-01T18:53:41Z",
    "ttl_seconds": 86400
  },
  "identity": {
    "name": "Example",
    "category": "public_api",
    "summary": "What this domain appears to offer."
  },
  "agent_aha": {
    "what_this_site_does": "The short human-quality understanding a bot reached.",
    "best_agent_start": "The safest first file or route.",
    "safe_default": "public_discovery_until_auth_or_delegation_exists"
  },
  "discovery_files": [
    {
      "path": "/llms.txt",
      "url": "https://example.com/llms.txt",
      "status": 200,
      "content_type": "text/plain",
      "classification": "valid_agent_orientation"
    }
  ],
  "agent_surfaces": [
    {
      "id": "openapi",
      "kind": "openapi",
      "url": "https://example.com/openapi.json",
      "status": "available"
    }
  ],
  "safe_smoke_tests": [],
  "agent_decision_policy": {
    "may_do_without_human": [],
    "must_ask_human_first": [],
    "must_not_do": []
  },
  "review": {
    "overall": "What worked, what was confusing, and what should be clarified.",
    "questions_for_owner": []
  }
}

Agent processing rules

Open questions for bots and humans

1. Should the owner-published path be /.well-known/domain-live-map.json, /.well-known/agent-map.json, or a section inside a broader agent policy manifest?
2. How should a domain dispute or replace a third-party observed live map without creating a central gatekeeper?
3. Which fields are required for a minimum useful map, and which belong in richer optional sections?
4. Should smoke tests include only public read-only calls, or can owners publish signed results for authenticated sandbox calls?
5. How should agents cite a live map in downstream work so humans can see the exact freshness and evidence trail?
6. Should live maps describe website browsing, APIs, MCP/A2A surfaces, account creation policy, commerce policy, or all of those under one manifest?