# ai.md — AI Visibility Foundation Spec **Version 1.0 · 2026-08-27 · Nameworthy (Whitley Row LLC) · https://nameworthy.ai/spec/** This file is written to be executed by an AI coding agent — Claude, ChatGPT, Cursor, a developer's agent — against a real business website. It is not a checklist for a human to read and feel informed by. Every task below ends in a definition of done that can be checked. It is free, public, and yours. There is no licence-back and nothing is withheld. **What this does:** it makes a business machine-readable, so an AI answer engine that reaches the site can identify the entity, understand what it sells and where, and quote it accurately. **What this does not do:** guarantee a citation, a recommendation, or a ranking. Readability is a precondition, not a cause. Anyone who tells you a technical retrofit guarantees an AI recommendation is selling you something they cannot deliver. See "The honest limit" at the end of this file. --- ## 0. Preamble — read before executing You are retrofitting an existing website. You are not rebuilding it. **Your job:** add and correct machine-readable structure. Leave the design, the brand, and the human-facing copy alone unless a task explicitly says otherwise. **Your posture:** conservative. This is a live business. A broken page costs the owner real money, and a fabricated fact costs them more than a missing one. **Never, under any circumstances:** - Invent a fact about the business. Not an address, a licence number, a founding year, a credential, a service, a price, or a staff name. If a value is required and you cannot verify it from the site or from something the owner told you, emit `TK` and report it as unresolved. **An omission is recoverable. A fabrication published under a business's name is not.** - Write, generate, edit, or solicit a review, testimonial, or third-party endorsement. Not on the site, not on a directory, not on a forum, not as a draft "for the owner to post." This is a hard stop with no exception. See §8. - Publish anything under a named person's byline without that person's explicit written approval. - Proceed past a failed precondition in §1. --- ## 1. Preconditions — confirm all five before touching anything Ask the operator directly. Do not infer. If any answer is no or unknown, **stop and report.** Do not proceed with the rest of this file. 1. **Domain control.** Can the operator publish changes to this domain's DNS and web root, or reach someone who can, today? 2. **Publishing authority.** Is the operator authorised by the business to publish public statements on its behalf? For a regulated practice, this usually means the managing partner, the medical director, or someone with their written delegation. 3. **Backup or version control.** Is the site under version control, or is there a current backup that can be restored? If neither, create a backup first. 4. **Staging.** Is there a staging environment or a preview deploy? If not, say so explicitly in your report — every task below becomes higher-risk and the operator should know that before you start. 5. **Regulated vertical.** Is this business in a regulated category — legal, medical, dental, financial, real estate, insurance? If yes, load the matching `profile-.md` and treat §8 as binding rather than advisory. **Definition of done:** five explicit answers recorded in your report. Not assumed. Not inferred from the site. --- ## 2. Task 1 — Schema.org entity graph The single highest-value item in this file. An engine that cannot resolve who a business *is* cannot recommend it as one. **Do:** 1. Load the schema types for this vertical from `profile-.md`. Do not guess types. 2. Emit one JSON-LD block per page, in ``, as `application/ld+json`. 3. Give every node a stable `@id` on the site's own domain — for example `https://example.com/#org`, `https://example.com/about/#founder`. 4. **Connect the nodes by `@id`, not by repetition.** A page's node references the organization node by `@id`; it does not restate it. Repetition without linkage is what produces a graph an engine cannot traverse. 5. Populate, only where you can verify each value: legal name, operating name, URL, logo, description, `areaServed`, `contactPoint`, and the vertical's required properties. 6. Add `sameAs` pointing at third-party records that **genuinely exist and resolve to real content** — the business's own profiles on directories, professional registries, and social platforms. **Do not:** - Add a `sameAs` URL that 404s, redirects to a parking page, or points at a placeholder. A `sameAs` pointing at nothing asserts a corroboration that cannot be checked, which is worse than no `sameAs` at all. Fetch every one and confirm it returns real content about this business before you include it. - Add `postalAddress` if the business has no premises the public may visit, or if the only available address is someone's home. Omitting it is a legitimate choice; publishing a home address to satisfy a schema shape is not. - Use `LocalBusiness` or a subtype for a remote practice with no customer-visiting premises. Use `Organization`. - Invent `aggregateRating`, `review`, or `priceRange`. `aggregateRating` on self-published markup with no verifiable source is a fabricated claim. **Definition of done:** every page emits valid JSON-LD; every `@id` referenced by another node resolves to a node that exists; every `sameAs` URL returns 200 with real content about this business; zero `TK` values remain unreported. --- ## 3. Task 2 — `ai.txt` and `agents.md` Two small files that state, in the open, what the site is and how an agent should treat it. - **`/ai.txt`** — plain text at the web root. Who the business is, what it does, the canonical URL, contact, and any usage terms the owner wants stated. - **`/agents.md`** — markdown at the web root. A short orientation for an agent arriving at the site: what lives where, which pages are canonical for which question, and what should not be quoted as current (pricing that changes, staff lists, anything dated). Keep both short and true. Their value is that they are unambiguous, not that they are long. **Definition of done:** both files return 200 as `text/plain` and `text/markdown` respectively; every URL inside them resolves; no claim in either contradicts the site or the entity graph. --- ## 4. Task 3 — `robots.txt` audit **Do not blanket-allow, and do not blanket-block.** Read the existing file first, state what it currently does in plain language, and change it deliberately. For each crawler below, the operator makes a decision and you record the reason: | Agent | Operator | What allowing it does | |---|---|---| | `GPTBot` | OpenAI | Training and retrieval corpus | | `OAI-SearchBot` | OpenAI | ChatGPT search results | | `ChatGPT-User` | OpenAI | Live fetch when a user's question triggers browsing | | `ClaudeBot` | Anthropic | Training and retrieval corpus | | `Claude-Web` | Anthropic | Live fetch during a conversation | | `PerplexityBot` | Perplexity | Index used to answer and cite | | `Google-Extended` | Google | Gemini and AI-surface grounding — **separate from Googlebot** | | `Googlebot` | Google | Ordinary search **and** AI Overviews / AI Mode | | `Bingbot` | Microsoft | Ordinary search and Copilot | | `Applebot` / `Applebot-Extended` | Apple | Siri, Spotlight, Apple Intelligence | **Two distinctions that are constantly confused, and getting them wrong is expensive:** 1. **Training access and retrieval access are different things.** Blocking `GPTBot` removes the site from a training corpus. It does not remove it from what ChatGPT retrieves live. Owners who "blocked AI" usually blocked training and are surprised to still be quoted — and owners who wanted to be quoted sometimes block the retrieval agent by accident. 2. **`Google-Extended` is not `Googlebot`.** Disallowing `Googlebot` removes the site from Google search *and* from Google's AI surfaces. Disallowing `Google-Extended` alone affects Gemini grounding and leaves search intact. **Also check, because it is the failure we see most often:** a `Disallow` inherited from a template, a staging config, or a plugin that nobody chose. Read what the file actually does before assuming the current state was intended. **Definition of done:** every agent above has an explicit allow or disallow with a one-line recorded reason; `robots.txt` returns 200; no `Disallow` remains that the operator cannot explain; a `Sitemap:` line points at the real sitemap. --- ## 5. Task 4 — sitemap with real `lastmod` **Do:** generate `sitemap.xml` covering every canonical, indexable URL. Give each entry a `lastmod` that reflects when that page's **content** last substantively changed. **Do not:** set `lastmod` to today for every page. Do not derive it from file mtime or from a git commit that touched styling, schema, or a typo. A sitemap that claims every page changed today is a sitemap that tells a crawler nothing, and repeated false freshness signals teach a crawler to discount the file. If you cannot determine a real per-page date, omit `lastmod` for that page. An absent date is honest; a manufactured one is not. **Definition of done:** sitemap parses as valid XML; every URL returns 200 and is canonical; no `lastmod` is in the future; `lastmod` values differ across pages unless the pages genuinely changed together; the file is referenced in `robots.txt`. --- ## 6. Task 5 — IndexNow on publish Wire an IndexNow ping so that publishing a page notifies participating engines directly rather than waiting to be recrawled. 1. Generate a key, host it at `https://example.com/.txt` containing the key. 2. On publish, POST the changed URLs to the IndexNow endpoint. 3. Submit only URLs that actually changed. Submitting the whole sitemap on every deploy is the same false-freshness failure as §5, and it is rate-limited. **Definition of done:** the key file returns 200 with the exact key as its body; a test submission returns a success response; the ping fires on publish and not on every build. --- ## 7. Task 6 — entity consistency pass The engines cross-check a business against records they did not get from its own site. Contradictions between those records lower confidence — the failure mode is not absence, it is disagreement. **Do:** make the business's name, address (where one is published at all), phone, hours, category, and URL **byte-identical** across: - Google Business Profile - Bing Places - Apple Business Connect - The directories and professional registries named in `profile-.md` **Identical means identical.** "Suite 200" and "Ste. 200" are two different addresses to a matcher. Pick one canonical form, write it down in the report, and use it everywhere including the entity graph in §2. **Do not:** create an account in a name that is not the business's own; use a mail-drop or registered-agent address that is not where the business operates; or publish a home address. If the only address available is residential, publish no address and say so in the report — several of these records accept a service-area business with no public street address. **Definition of done:** a table in your report, one row per record, showing the value at each source and an explicit match or mismatch; every mismatch either fixed or listed as blocked with the reason. --- ## 8. Task 7 — page-structure retrofit Engines quote passages, not pages. The unit of retrieval is a self-contained chunk that answers one question. **Do, on service and answer pages:** - One `

` per page, stating what the page is about in the words a customer would use. - `

`/`

` in real hierarchy, each heading naming the question its section answers. - **Answer-first opening paragraph.** The first paragraph after a heading answers the heading's question directly, in one or two sentences, without preamble and without requiring the paragraph before it for context. A passage that only makes sense in situ cannot be lifted. - An FAQ block on service pages, marked up as `FAQPage`, where the questions are ones customers actually ask and every answer is true and specific. - Facts stated where they can be lifted: what is offered, where, by whom, with what credential, verifiable at a named source. **Do not:** - Generate clinical outcome claims, efficacy claims, comparative superiority claims ("best", "leading", "#1"), or case-result claims. **Hard stop.** - Generate testimonials, reviews, endorsements, or "representative" customer quotes. **Hard stop, no exceptions**, including drafts labelled as examples. - Publish content under a provider's or attorney's byline without that person's written review. **Hard stop.** - Rewrite human-facing brand copy because it would read better to a machine. The business has a voice; you are adding structure to it. **Escalate to a human before publishing** anything that states a credential, a legal or medical fact, a price, a guarantee, or a claim about outcomes. For a regulated practice that human is the medical director or managing partner, not the operator running this file. **Definition of done:** every retrofitted page has exactly one `

`; heading hierarchy has no skipped levels; every section's first paragraph answers its own heading standalone; every FAQ answer is verifiable; zero hard-stop violations; every escalated item recorded with who approved it and when. --- ## 9. Deliberately omitted: `llms.txt` `llms.txt` is not in the task list above, and that is a decision rather than an oversight. [Ahrefs studied 137,210 domains](https://ahrefs.com/blog/llmstxt-study/) and found that 28% publish an `llms.txt` — and that **97% of those files received no traffic at all** in the month measured. Adoption is real. The reading is not. We publish one on our own site and treat it as hygiene, not a lever. Add one if you want to; it costs ten minutes. It is excluded from the ordered tasks because this spec does not ask an agent to spend effort on something the evidence says is not being fetched, and because a named deliverable that does nothing is how buyers get sold packages by the item. If a future study shows retrieval, this section changes and the version number moves. That is what the changelog is for. --- ## 10. Verification When every applicable task is done, execute `verify.md` from this same directory and produce its dated report. **A task is not complete until it is verified.** Report honestly. If a task was skipped, say it was skipped and why. If a check failed, report the failure rather than the intent. An agent that reports success it did not achieve produces exactly the problem this spec exists to prevent. **Then hand the operator `measure.md`.** Verification proves the site is readable; it proves nothing about what an engine now says. `measure.md` is the by-hand protocol for finding that out, and it is written for a person rather than an agent on purpose — the consumer apps cannot be scripted without measuring an API instead, which is a different product. The sequence is: build, verify, measure, measure again in thirty days. --- ## 11. Design rules for anyone forking this file - **Idempotent.** Running it twice must be safe and must not duplicate nodes, files, or directory entries. - **Failure-tolerant.** Every task states what to do when it cannot complete: skip and report. Never guess and proceed. - **Agent-agnostic.** No tool-specific syntax. If it only runs in one product it is a plugin, not a spec. - **Versioned and dated.** This is a live document about a moving target. Crawler names change, schema vocabulary evolves, engine behaviour shifts. --- ## The honest limit This spec makes a business **readable**. Whether it gets **recommended** depends on things no retrofit controls: what else exists in the market, what third parties say about the business, and which sources each engine happens to select this week. Two published findings worth holding onto while you run this: - In our own cross-panel measurement — 383 first-position transition pairs across six engines — an unmanaged #1 AI recommendation had an expected lifetime of roughly **one to two days**. - SISTRIX, measuring 82,619 prompts over 17 weeks, found ChatGPT replacing **up to 74% of its cited sources every week**. So: run this file, and the site becomes legible to the engines. Whether that legibility turned into a recommendation, and whether the recommendation held, is a measurement question — and measuring it repeatedly, per engine, from a clean vantage, is the part you cannot do with a spec. That is the honest boundary of this document, and we would rather state it than let you discover it in ninety days. --- *Nameworthy publishes this spec free and in full because the file was never the valuable part. Measurement is. — https://nameworthy.ai/spec/*