# The .well-known Directory: Your Site's Machine-Readable Identity Hub The .well-known directory is how machines discover your site's identity, security contacts, AI capabilities, and federation endpoints. Here's the complete guide to every file that matters in 2026. Author: J.A. Watte Published: May 5, 2026 Source: https://jwatte.com/blog/blog-well-known-directory-guide/ --- 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 reports - `Expires` (required). When this file should be considered stale - `Preferred-Languages`. Languages you can accept reports in - `Canonical`. The definitive URL for this file - `Policy`. 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 most important `.well-known` file for 2026. As AI agents become a significant source of web traffic, `agent-card.json` provides structured discovery metadata. ```json { "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](/blog/blog-ai-agent-cards-2026/), 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. ```json { "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: ```json { "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](https://the100dollarnetwork.com/). Including deployment automation for multi-site networks and the complete `.well-known` template set. [Buy The $100 Network on Amazon](https://the100dollarnetwork.com/). ## Related reading The methodology behind this piece is covered in depth in: - **[The $97 Launch](https://the97dollarlaunch.com/)**, Domain, hosting, deploy, and indexing stack for getting a site into search quickly. - **[The $100 Network](https://the100dollarnetwork.com/)**, Monoclone architecture, IndexNow, and multi-site scaling, how to run a network of sites. --- Canonical HTML: https://jwatte.com/blog/blog-well-known-directory-guide/ RSS: https://jwatte.com/feed.xml JSON Feed: https://jwatte.com/feed.json Hero image: https://jwatte.com/images/blog-well-known-directory-guide.webp