AIDOC

a structured action-graph for AI agents
Concept prototype
Where this sits: llms.txt tells an agent what a site is about, in prose. AIDOC describes what an agent can do on a site: which pages exist, what actions they expose, what parameters they take. They're complementary, not competing — a site can ship both.

What a draft AIDOC file looks like

The actual generator would crawl a site and produce this. A site owner still has to review, sign, and host it themselves before any agent should trust it — see the Trust Model tab for why that step isn't optional.

Example output, for a small storefront

{ "version": "0.1", "domain": "example.com", "generated_at": "2026-07-02T00:00:00Z", "pages": [ { "path": "/", "purpose": "home", "actions": ["nav", "search"], "links_to": ["/products", "/about", "/contact"] }, { "path": "/products", "purpose": "catalog", "actions": ["filter", "sort", "add_to_cart"], "params": ["category", "price_range"], "links_to": ["/products/{id}", "/checkout"], "template": true }, { "path": "/products/{id}", "purpose": "product_detail", "actions": ["add_to_cart", "review", "share"], "template": true, "links_to": ["/checkout", "/products"] }, { "path": "/api/v1/search", "purpose": "api_search", "methods": ["GET", "POST"], "params": ["q", "limit", "offset"], "response": "json_array", "auth": "none", "rate_limit": "100/min" } ] }

Field names are spelled out, not single letters. A byte-optimized .min.json variant can be generated separately for production hosting — see Comparison.

How this compares

Numbers below are illustrative, from one example site. Actual savings depend entirely on site size and structure — nobody should quote a fixed percentage without measuring their own case.

Format Purpose Example size Est. tokens
sitemap.xml URL list for search crawlers 18.5 KB ~4,200
llms.txt Prose overview for LLM readers 3-8 KB (varies widely) no structured schema
AIDOC Structured action graph for agents 2.3 KB (this example) ~650

llms.txt (prose, for reading)

# Example Co > An online store selling handmade goods. ## Products Browse the [catalog](/products). Each item has a detail page with reviews and a buy button. ## API A search endpoint is available at /api/v1/search.

Good for a human-like summary. An agent still has to infer parameters and affordances from prose.

AIDOC (structured, for acting)

{ "pages": [ { "path": "/products", "purpose": "catalog", "actions": ["filter", "sort"], "links_to": ["/products/{id}"] } ] }

Explicit fields an agent can parse directly, no inference needed.

The real open problem: can an agent trust this file?

Why this matters more than compression

A manifest is self-reported by whoever generates it. A field like "auth": "none" being wrong is a much bigger risk to an agent than a slow crawl would have been. Any design that skips provenance is optimizing the wrong variable.

Proposed baseline, borrowed from existing conventions

  • Same-origin only. An agent should only trust an AIDOC file served from the domain it describes, at a fixed path — the same pattern robots.txt and security.txt (RFC 9116) already use: /.well-known/aidoc.json. A third party generating one for a domain it doesn't control should never be treated as authoritative.
  • Owner attestation. The file is signed with a key whose fingerprint is published via DNS TXT record on the same domain, so possession of the domain implies possession of the claims.
  • Freshness check. Agents spot-check a small sample of claimed pages against the live site before relying on the manifest for anything consequential, like a checkout flow.
  • Scoped trust. Navigation hints (what links to what) are low-stakes if wrong. Auth and rate-limit claims are high-stakes. Treat them differently rather than trusting the whole file uniformly.

What this tool is, honestly

A drafting aid. It crawls and proposes a manifest a site owner can review, edit, sign, and publish themselves. It is not a trust authority, and it does not make any claim about a site it didn't generate for. That distinction is the whole point.

AIDOC format specification (draft)

Overview

AIDOC is a structured, machine-parseable description of a site's pages, actions, and API surface, intended for AI agents that need to act on a site rather than just read it. It's meant to sit alongside llms.txt, not replace it.

Top-level fields

  • version: spec version
  • domain: the domain this manifest describes
  • generated_at: ISO 8601 timestamp
  • pages: array of page objects

Page object fields

  • path: URL path
  • purpose: short label for the page's function
  • actions: interactions available on the page
  • params: query or form parameters
  • links_to: outbound navigation targets
  • methods: HTTP methods, for API-like pages
  • response: response shape, for API-like pages
  • template: boolean, true if the path represents a parameterized template rather than a single page

Field names are spelled out on purpose. A separate minified build step can shorten keys for production hosting without forcing every consumer to memorize a cipher — legibility and byte count don't have to trade off against each other in the source spec.

Hosting convention

Served at /.well-known/aidoc.json on the domain it describes. See Trust Model for why same-origin hosting is a hard requirement, not a suggestion.

Draft-to-publish workflow

From crawl to a signed manifest an agent can actually rely on. Owner review and signing are non-optional steps, not implementation details.

75% Scroll to pan
INPUT
Website URL
https://example.com
Config
Depth: 3, APIs: yes
→
CRAWL
Crawler
Pages, forms
Analyzer
Actions, links
Raw data
~500 KB
→
DRAFT
Manifest compiler
Structure the graph
Draft manifest
Needs owner review
→
OWNER REVIEW
Edit & correct
Fix auth, rate limits
Sign & publish
/.well-known/aidoc.json
→
AGENT USE
Fetch + verify signature
Reject if unsigned
Spot-check sample
Before high-stakes use
Act on the site
Direct navigation
Input
Processing / needs attention
Trusted output
Storage
Agent-side verification

The step that's easy to skip in a demo, and the one that actually matters, is Owner Review. A manifest an agent can act on without checking is only safe once a human who controls the domain has looked at it.