{
  "$comment": "Guidance for AI agents authoring AI Discovery Files on behalf of a site owner. The file specifications define what a valid file contains; this defines how to produce one responsibly.",
  "protocol": "adf-authoring-guidance",
  "version": "1.0.0",
  "lastUpdated": "2026-08-24",
  "documentation": {
    "human": "https://discoveryfiles.ai/in-practice/for-ai-agents",
    "markdown": "https://discoveryfiles.ai/agent/authoring.md",
    "specifications": "https://discoveryfiles.ai/specifications"
  },
  "primeDirective": {
    "rule": "Never invent a fact about the target business. Every value you write must come from the target site itself, from the site owner, or be omitted entirely. It must never come from your own prior assumptions about the company.",
    "rationale": "These files exist so AI systems stop guessing about a business. A file authored by guessing defeats its own purpose — and because identity.json is the authoritative record other files must agree with, a single invented value propagates into every other file and becomes the thing future systems treat as true."
  },
  "hardRules": [
    "Never invent a fact about the business. Omit instead.",
    "identity.json is authoritative. Every other file must agree with it.",
    "No superlatives, no prices, no competitor references, anywhere.",
    "Never grant AI training permission the owner has not explicitly given.",
    "Never write credentials, internal hostnames or staging URLs into developer-ai.txt.",
    "robots-ai.txt must not contradict robots.txt. robots.txt wins regardless.",
    "Every file needs a Last Updated date reflecting when it was actually written.",
    "Replace every bracketed placeholder, or delete the section containing it.",
    "Files go at the domain root. Language variants go at language paths, e.g. /fr/llms.txt.",
    "Report omissions to the owner rather than filling them silently."
  ],
  "factSources": {
    "derivableFromSite": {
      "rule": "Safe to take directly from the target site’s own public pages, because the owner published them.",
      "examples": [
        "Services and products described on the site",
        "Public contact addresses, phone numbers and postal addresses",
        "Office or location names listed publicly",
        "Social profile URLs linked from the site",
        "Existing page URLs for the link sections of llms.txt",
        "The site’s primary language"
      ]
    },
    "mustAskOwner": {
      "rule": "Cannot be reliably scraped and must not be guessed. If the owner cannot answer, omit the field rather than fill it.",
      "examples": [
        "Registered legal entity name, if it differs from the trading name",
        "Company registration number and VAT number",
        "Founding date",
        "Services the business explicitly does NOT offer",
        "Markets or regions explicitly NOT served",
        "Whether AI training on their content is permitted",
        "Brand forms that must never be used — retired names, wrong abbreviations",
        "The contact address for AI-related enquiries"
      ]
    },
    "neverWrite": {
      "rule": "Prohibited by the specifications, or too risky for an agent to decide unilaterally.",
      "examples": [
        "Any superlative — \"leading\", \"world-class\", \"best-in-class\", \"innovative\"",
        "Prices, which change faster than files are updated",
        "Headcount, revenue or funding figures not stated on the site",
        "Competitor names or comparative claims",
        "Testimonials, reviews or quotes you cannot source",
        "Credentials, API keys, internal hostnames or staging URLs",
        "A permissive AI training grant the owner has not explicitly given"
      ]
    }
  },
  "procedure": [
    {
      "step": 1,
      "title": "Check what already exists",
      "detail": "Fetch every path before writing anything. A site may already publish files that someone maintains deliberately. Overwriting a maintained brand.txt with your own inference is a regression, not an improvement.",
      "commands": [
        "for f in llms.txt llm.txt llms-full.txt llms.html identity.json ai.json ai.txt brand.txt robots-ai.txt faq-ai.txt developer-ai.txt; do curl -sS -o /dev/null -w \"%{http_code}  %{content_type}  $f\\n\" \"https://example.com/$f\"; done"
      ],
      "stopCondition": "If files already exist and look maintained, propose edits to the owner rather than replacing them."
    },
    {
      "step": 2,
      "title": "Read the target site",
      "detail": "Gather what the owner has already published: services, locations, contacts, the language of the site, and the URLs worth linking. Note the exact wording the site uses about itself — matching it keeps the files consistent with the pages they describe."
    },
    {
      "step": 3,
      "title": "Ask the owner for the gaps",
      "detail": "Present the “Ask the site owner” list as a short questionnaire. Ask for all of it at once rather than one question at a time. Make clear that unanswered items will be omitted, not guessed — that is a feature, and it usually prompts an answer.",
      "stopCondition": "Do not write identity.json without the registered business name and founding year confirmed, or explicitly waived."
    },
    {
      "step": 4,
      "title": "Write the Layer 1 files first",
      "detail": "llms.txt and identity.json are Required — start there. Getting those right matters more than publishing all eleven. Start from the published templates rather than composing from memory: they carry the required section structure.",
      "commands": [
        "curl -sS https://discoveryfiles.ai/agent/templates/llms.txt",
        "curl -sS https://discoveryfiles.ai/agent/templates/identity.json"
      ]
    },
    {
      "step": 5,
      "title": "Propagate the Core Identity block",
      "detail": "llms.txt is the source of truth. Write its Core Identity block from confirmed facts only, then repeat it word for word in every other file that carries it. Cross-file contradiction is the failure mode these specifications care most about."
    },
    {
      "step": 6,
      "title": "Decide crawler policy with the owner, not for them",
      "detail": "robots-ai.txt and any AI training stance are business decisions, not technical ones. Explain the trade-off — blocking a training crawler is different from blocking a search crawler, and blocking the latter removes the business from that assistant’s answers — then implement what the owner chooses.",
      "stopCondition": "Never grant AI training permission without an explicit instruction from the owner."
    },
    {
      "step": 7,
      "title": "Validate",
      "detail": "Run the repository validator over the finished files. Do not skip this because the output \"looks right\" — the validator catches exactly the errors that are invisible to reading.",
      "commands": [
        "git clone --depth 1 https://github.com/GenerellAI/ai-discovery-files",
        "./ai-discovery-files/scripts/validate.sh path/to/your/files/"
      ]
    },
    {
      "step": 8,
      "title": "Verify how they are served",
      "detail": "A valid file served with the wrong Content-Type, or behind a soft 404, is an unreadable file. Confirm the status line and content type after deploying — this is the only check that proves the work landed.",
      "commands": [
        "curl -sSI https://example.com/llms.txt | grep -i '^HTTP\\|^content-type'"
      ]
    },
    {
      "step": 9,
      "title": "Report what you omitted",
      "detail": "Tell the owner exactly which fields you left out and why, and which values came from them versus from their site. An omission they can fill in later is a good outcome; a plausible invention they never notice is the bad one."
    }
  ],
  "layers": [
    {
      "ordinal": "Layer 1",
      "name": "Core Identity",
      "guidance": "Establishes who you are and makes it readable by both machines and people. Start here — everything else refers back to it.",
      "files": [
        "llms.txt",
        "llm.txt",
        "llms-full.txt",
        "llms.html",
        "identity.json",
        "ai.json"
      ]
    },
    {
      "ordinal": "Layer 2",
      "name": "Guidance & Control",
      "guidance": "Sets the rules: when to recommend you, how to name you, and how AI crawlers should treat your content.",
      "files": [
        "ai.txt",
        "brand.txt",
        "robots-ai.txt"
      ]
    },
    {
      "ordinal": "Layer 3",
      "name": "Enhancement",
      "guidance": "Adds verified answers and technical context, so AI systems have something specific to quote instead of inferring.",
      "files": [
        "faq-ai.txt",
        "developer-ai.txt"
      ]
    }
  ],
  "priorities": {
    "Required": "Publish this. Without it there is no authoritative identity to read.",
    "Recommended": "Publish this unless you have a specific reason not to.",
    "Optional": "Publish when you want the extra control it gives.",
    "Conditional": "Publish only when the condition applies to your site."
  },
  "files": [
    {
      "filename": "llms.txt",
      "layer": "Core Identity",
      "priority": "Required",
      "purpose": "Your identity, in the format AI systems read first.",
      "format": "Markdown, UTF-8, served as text/plain",
      "mustContain": [
        "An H1 with your brand name",
        "A one-sentence factual summary as a blockquote",
        "The Core Identity block, word for word consistent across files",
        "A Last updated date"
      ],
      "publishAt": "https://{domain}/llms.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/llms.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/llms-txt.md",
      "authoringNote": "The source of truth. The Core Identity block here must appear word for word in every other file that carries it."
    },
    {
      "filename": "llm.txt",
      "layer": "Core Identity",
      "priority": "Required",
      "purpose": "A compatibility copy for systems that ask for the singular name.",
      "format": "301 redirect to llms.txt, or an identical copy",
      "mustContain": [
        "Same content as llms.txt, or a 301 to it",
        "Never a second, diverging source of truth"
      ],
      "publishAt": "https://{domain}/llm.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/llm.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/llm-txt.md",
      "authoringNote": "Preferred implementation is a 301 redirect from /llm.txt to /llms.txt. Use a literal copy only if your host cannot issue redirects."
    },
    {
      "filename": "llms-full.txt",
      "layer": "Core Identity",
      "priority": "Conditional",
      "condition": "Use when a concise llms.txt cannot cover your important public pages clearly.",
      "purpose": "The expanded companion, when one file is not enough.",
      "format": "Markdown, UTF-8, served as text/plain",
      "mustContain": [
        "The same Core Identity block as llms.txt",
        "Broader link coverage, not contradictory detail",
        "A link back to llms.txt as canonical"
      ],
      "publishAt": "https://{domain}/llms-full.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/llms-full.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/llms-full-txt.md",
      "authoringNote": "Only publish this if a concise llms.txt cannot cover your important public pages. Same format, broader coverage — never contradictory detail."
    },
    {
      "filename": "llms.html",
      "layer": "Core Identity",
      "priority": "Recommended",
      "purpose": "The same information, readable by people.",
      "format": "HTML5, optionally with Schema.org structured data",
      "mustContain": [
        "Content that matches llms.txt",
        "No tracking scripts or advertising",
        "A link to the canonical llms.txt"
      ],
      "publishAt": "https://{domain}/llms.html",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/llms.html",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/llms-html.md",
      "authoringNote": "Every fact here must already appear in llms.txt. No analytics, no ads, nothing hidden from human visitors."
    },
    {
      "filename": "identity.json",
      "layer": "Core Identity",
      "priority": "Required",
      "purpose": "Your identity as structured, parseable data.",
      "format": "Strict JSON, UTF-8, served as application/json",
      "mustContain": [
        "Core Identity fields matching llms.txt",
        "Schema.org-aligned structure",
        "Contact points",
        "A lastUpdated value"
      ],
      "publishAt": "https://{domain}/identity.json",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/identity.json",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/identity-json.md",
      "authoringNote": "Structured version of the same identity. Keep names, contacts and dates identical to llms.txt."
    },
    {
      "filename": "ai.json",
      "layer": "Core Identity",
      "priority": "Recommended",
      "purpose": "Structured identity plus recommendation signals.",
      "format": "Strict JSON, UTF-8, served as application/json",
      "mustContain": [
        "Core Identity fields matching llms.txt",
        "Recommendation and policy signals",
        "Values consistent with ai.txt"
      ],
      "publishAt": "https://{domain}/ai.json",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/ai.json",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/ai-json.md",
      "authoringNote": "Structured identity plus recommendation signals. Must agree with ai.txt wherever the two overlap."
    },
    {
      "filename": "ai.txt",
      "layer": "Guidance & Control",
      "priority": "Recommended",
      "purpose": "When AI should recommend you — and when it should not.",
      "format": "Plain text with headed sections",
      "mustContain": [
        "The Core Identity block",
        "Recommend / do not recommend guidance",
        "Clear, specific and actionable statements"
      ],
      "publishAt": "https://{domain}/ai.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/ai.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/ai-txt.md",
      "authoringNote": "Be specific about when you should and should not be recommended. Vague guidance is not actionable."
    },
    {
      "filename": "brand.txt",
      "layer": "Guidance & Control",
      "priority": "Recommended",
      "purpose": "How to name you correctly — and how not to.",
      "format": "Plain text with headed sections",
      "mustContain": [
        "Official and legal names",
        "Naming rules and forms to avoid",
        "Voice and tone guidance"
      ],
      "publishAt": "https://{domain}/brand.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/brand.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/brand-txt.md",
      "authoringNote": "List every wrong form you have ever been called. This is the file that prevents invented abbreviations."
    },
    {
      "filename": "robots-ai.txt",
      "layer": "Guidance & Control",
      "priority": "Optional",
      "purpose": "Citation preferences and crawler-level guidance for AI.",
      "format": "robots.txt-style syntax",
      "mustContain": [
        "Citation and freshness preferences",
        "Rules consistent with robots.txt, which still wins"
      ],
      "publishAt": "https://{domain}/robots-ai.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/robots-ai.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/robots-ai-txt.md",
      "authoringNote": "This supplements robots.txt, it does not replace it. Where the two disagree, robots.txt wins — so keep them consistent."
    },
    {
      "filename": "faq-ai.txt",
      "layer": "Enhancement",
      "priority": "Recommended",
      "purpose": "Verified answers, written to be quoted.",
      "format": "Structured plain text",
      "mustContain": [
        "The Core Identity block",
        "Questions drawn from real enquiries",
        "Answers supported by public content"
      ],
      "publishAt": "https://{domain}/faq-ai.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/faq-ai.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/faq-ai-txt.md",
      "authoringNote": "Write every answer as if it will be pasted straight into a chat reply. Facts only, each supported by a public page."
    },
    {
      "filename": "developer-ai.txt",
      "layer": "Enhancement",
      "priority": "Conditional",
      "condition": "Use when your product exposes APIs, SDKs or integration workflows.",
      "purpose": "Technical context for developer-facing questions.",
      "format": "Plain text with headed sections",
      "mustContain": [
        "The Core Identity block",
        "API status and authentication summary",
        "Links to real documentation",
        "No credentials, internal URLs or unreleased features"
      ],
      "publishAt": "https://{domain}/developer-ai.txt",
      "templateUrl": "https://discoveryfiles.ai/agent/templates/developer-ai.txt",
      "specificationUrl": "https://github.com/GenerellAI/ai-discovery-files/blob/main/specs/developer-ai-txt.md",
      "authoringNote": "Context, not documentation. Never include credentials, staging URLs, admin paths or unreleased features."
    }
  ],
  "validation": {
    "repository": "https://github.com/GenerellAI/ai-discovery-files",
    "command": "./ai-discovery-files/scripts/validate.sh path/to/your/files/",
    "servingCheck": "curl -sSI https://{domain}/llms.txt | grep -i '^HTTP\\|^content-type'",
    "expected": {
      "status": 200,
      "textContentType": "text/plain; charset=utf-8",
      "jsonContentType": "application/json; charset=utf-8"
    },
    "note": "A soft 404 — a styled error page returned with status 200 — reads to a consumer as a valid file containing your error page. Always check the status line, not just that a body came back."
  },
  "notes": {
    "sourceOfTruth": "llms.txt is the source of truth. The Core Identity block must appear word for word in every file that carries it.",
    "llmsTxtFormat": "https://llmstxt.org",
    "specifications": "https://github.com/GenerellAI/ai-discovery-files"
  }
}