Every website has a front door for humans. It is your homepage. But in 2026, your site also needs a front door for machines — and that front door is the .well-known directory.
The .well-known URI path is an IETF standard (RFC 8615) that provides a predictable location for machine-readable metadata about your site. When a security researcher needs to report a vulnerability, they check /.well-known/security.txt. When an AI agent wants to understand your site, it checks /.well-known/agent-card.json. When a federation protocol needs to discover your identity, it checks /.well-known/webfinger.
I just deployed a complete .well-known directory across 52 websites. Here is every file that matters, why it matters, and how to implement each one.
security.txt: Your Vulnerability Reporting Policy
File: /.well-known/security.txt
Standard: RFC 9116
Purpose: Tells security researchers how to report vulnerabilities in your site
This is the oldest and most established .well-known file. If a researcher finds a security issue on your site — an exposed database, a misconfigured API, a cross-site scripting vulnerability — security.txt tells them who to contact and how.
Contact: mailto:security@yoursite.com
Expires: 2027-04-14T00:00:00.000Z
Preferred-Languages: en
Canonical: https://yoursite.com/.well-known/security.txt
Policy: https://yoursite.com/security-policy/
Key fields:
Contact(required) — email, URL, or phone number for security reportsExpires(required) — when this file should be considered stalePreferred-Languages— languages you can accept reports inCanonical— the definitive URL for this filePolicy— link to your full vulnerability disclosure policy
Without security.txt, researchers who find vulnerabilities often have no way to report them responsibly. They email generic contact addresses, submit web forms that go to marketing teams, or simply give up. The vulnerability stays open.
agent-card.json: Your AI Agent Identity
File: /.well-known/agent-card.json
Purpose: Tells AI agents who you are, what you offer, and how to interact with your site
This is the newest and arguably most important .well-known file for 2026. As AI agents become a significant source of web traffic, agent-card.json provides structured discovery metadata.
{
"schema_version": "1.0",
"name": "Your Site Name",
"description": "What your site does",
"url": "https://yoursite.com",
"capabilities": ["content_discovery", "product_information"],
"contact": {
"email": "hello@yoursite.com"
},
"interaction": {
"accepts_automated_queries": true,
"rate_limit": "60/minute"
}
}
I covered agent cards in detail in a separate post, but the key point here is that this file serves as the authoritative machine-readable description of your site for autonomous AI systems. Without it, agents infer your identity from your HTML. With it, you control the narrative.
ai-plugin.json: ChatGPT Plugin Discovery
File: /.well-known/ai-plugin.json
Purpose: Describes your site as a ChatGPT plugin or AI tool integration endpoint
OpenAI introduced this format for ChatGPT plugin discovery. Even if you are not building a full ChatGPT plugin, having this file signals to AI systems that your site has structured capabilities.
{
"schema_version": "v1",
"name_for_human": "Your Site Name",
"name_for_model": "your_site",
"description_for_human": "What your site does for humans",
"description_for_model": "Structured description for AI consumption",
"auth": {
"type": "none"
},
"api": {
"type": "openapi",
"url": "https://yoursite.com/openapi.yaml"
},
"logo_url": "https://yoursite.com/logo.png",
"contact_email": "hello@yoursite.com",
"legal_info_url": "https://yoursite.com/legal/"
}
The description_for_model field is particularly valuable. It is your elevator pitch to AI systems — a concise, keyword-rich description of what your site offers, optimized for machine comprehension rather than human marketing.
webfinger: Federation and Identity Discovery
File: /.well-known/webfinger
Standard: RFC 7033
Purpose: Enables cross-platform identity discovery for federation protocols
Webfinger is how Mastodon, Bluesky (via bridging), and other federated platforms discover your identity. When someone searches for @you@yoursite.com on Mastodon, their server queries https://yoursite.com/.well-known/webfinger?resource=acct:you@yoursite.com.
For static sites, you can create a webfinger file that handles your primary identity:
{
"subject": "acct:you@yoursite.com",
"links": [
{
"rel": "http://webfinger.net/rel/profile-page",
"type": "text/html",
"href": "https://yoursite.com"
},
{
"rel": "self",
"type": "application/activity+json",
"href": "https://yoursite.com/activitypub/actor"
}
]
}
Even if you are not running a full ActivityPub server, a webfinger file that redirects to your Mastodon profile allows people to find you using your domain as your identity handle.
robots.txt: Still Essential, Now AI-Aware
File: /robots.txt (not technically in .well-known, but part of the same ecosystem)
Purpose: Controls which crawlers can access which parts of your site
In 2026, robots.txt has new relevance because of AI crawlers. You now need to make explicit decisions about:
User-agent: GPTBot
Allow: /
User-agent: Google-Extended
Allow: /
User-agent: CCBot
Disallow: /
User-agent: anthropic-ai
Allow: /
Each AI company has its own crawler. You can allow or block them individually. The decision depends on your business model — if you want AI citation, allow the crawlers. If you want to protect content behind a paywall, block them.
llms.txt: AI-Specific Content Guidance
File: /llms.txt
Purpose: Tells LLMs what your site is about and how to represent it
This file is a plain-text briefing for large language models. Unlike robots.txt which controls access, llms.txt provides context:
# Your Site Name
> One-sentence description of your site.
## About
Two to three paragraphs explaining who you are, what you publish, and what you're an authority on.
## Key Topics
- Topic 1
- Topic 2
- Topic 3
## Contact
- Email: hello@yoursite.com
- Website: https://yoursite.com
When an LLM encounters your site during training or retrieval, llms.txt gives it a structured understanding of your identity and expertise. We saw improved accuracy in how AI systems describe our sites after deploying this file.
The Complete .well-known Audit Checklist
Here is every file you should evaluate for your .well-known directory:
| File | Priority | Purpose |
|---|---|---|
security.txt |
High | Vulnerability reporting |
agent-card.json |
High | AI agent discovery |
ai-plugin.json |
Medium | ChatGPT/AI plugin discovery |
webfinger |
Medium | Federation identity |
change-password |
Low | Password manager support |
assetlinks.json |
Low | Android app linking |
apple-app-site-association |
Low | iOS app linking |
Plus these root-level files that work alongside .well-known:
| File | Priority | Purpose |
|---|---|---|
robots.txt |
High | Crawler control |
llms.txt |
High | LLM context |
humans.txt |
Low | Team credits |
ads.txt |
Medium | Ad fraud prevention |
Deployment Tips for Static Sites
If you run a static site generator (Eleventy, Hugo, Astro, Next.js), you need to ensure the .well-known directory survives the build process:
- Eleventy: Add
eleventyConfig.addPassthroughCopy(".well-known")to your config - Hugo: Place files in the
static/.well-known/directory - Astro: Place files in the
public/.well-known/directory - Next.js: Place files in the
public/.well-known/directory
On Cloudflare Pages, verify that the files are accessible after deployment — some configurations strip dot-prefixed directories.
Why This Matters
The .well-known directory is your site's machine-readable identity hub. Every file in it serves a different audience — security researchers, AI agents, federation protocols, app stores — but together they form a complete picture of who you are and how machines should interact with you.
Most websites have zero .well-known files. Some have a security.txt. Almost none have the full stack. That is an opportunity. The sites that invest 30 minutes in building out this directory will be more discoverable, more trustworthy, and more integrated with the machine-readable web than their competitors.
This strategy is covered in more depth in The $100 Network — including deployment automation for multi-site networks and the complete .well-known template set. Buy The $100 Network on Amazon.