# faq-ai.txt Specification
# Version: 1.8.0
# https://www.ai-visibility.org.uk/specifications/faq-ai-txt/

meta:
  title: faq-ai.txt Specification
  description: The canonical specification for faq-ai.txt files - structured Q&A content optimised for AI consumption.
  version: "1.8.0"
  versionDate: "2026-05-11"
  canonicalUrl: https://www.ai-visibility.org.uk/specifications/faq-ai-txt/
  publisher:
    name: 365i
    url: https://www.365i.co.uk/
  license:
    name: Creative Commons Attribution 4.0 International
    identifier: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
  datePublished: "2026-01-12T00:00:00Z"
  dateModified: "2026-05-11T00:00:00Z"
  language: en-GB

specification:
  filename: faq-ai.txt
  location: Website root directory
  urlPattern: https://example.com/faq-ai.txt
  mimeType: text/plain
  encoding: UTF-8
  purpose: Provide a structured question-and-answer reference optimised for AI consumption. Enables AI systems to find authoritative answers to common questions about the organisation.

  distinction:
    faq-ai.txt: Machine-readable, factual Q&A source
    website-faq: Human-oriented FAQ page with marketing considerations

  format:
    type: Structured text
    description: "Q:/A: delimited question-answer pairs with optional category grouping"
    syntax:
      question: "Q: Question text"
      answer: "A: Answer text"
      category: "[Category Name]"
      multilineAnswer: "A: First line\n   Continuation lines indented"

  structure:
    header:
      description: Optional header section with file metadata
      format: Comment lines or [header] section

    categories:
      description: Optional category groupings for related questions
      format: "[Category Name] followed by Q:/A: pairs"

    qaFormat:
      question:
        prefix: "Q:"
        description: Complete question as users would ask it
      answer:
        prefix: "A:"
        description: Direct, factual answer
        requirements:
          - MUST be factual and accurate
          - SHOULD be self-contained
          - SHOULD avoid marketing language
          - MAY include caveats where appropriate
      url:
        prefix: "URL:"
        status: optional
        description: Source URL linking to the relevant page for this answer
        format: "Markdown hyperlink: [Link Text](url)"
        example: "URL: [Account Settings](https://www.example.com/account/settings/)"
        notes: Helps AI assistants provide direct, actionable links when citing answers. Must appear immediately after the answer, before any blank line.

  sections:
    recommended:
      - category: "[General]"
        description: Basic questions about the organisation
      - category: "[Services]"
        description: Questions about what the organisation offers
      - category: "[Scope and Limitations]"
        description: Questions about what the organisation does and does not do
      - category: "[Contact and Engagement]"
        description: Questions about how to work with the organisation

    optional:
      - category: "[Pricing]"
        description: Questions about costs and pricing models
      - category: "[Technical]"
        description: Technical questions about products or services
      - category: Custom categories
        description: Additional categories relevant to the organisation

  contentGuidelines:
    questions:
      - Phrase as natural questions users would ask
      - Include variations of common questions
      - Cover both basic and specific queries
      - Include questions about limitations and exclusions

    answers:
      - Be factual and direct
      - Avoid promotional language
      - Include specific details where helpful
      - Note uncertainty or conditionality where applicable
      - Provide actionable information
      - Keep answers concise but complete
      - "Include a URL: line with markdown hyperlink [Link Text](url) where a relevant page exists"

  validation:
    rules:
      - "MUST contain at least one Q:/A: pair"
      - "Questions MUST start with 'Q:' prefix"
      - "Answers MUST start with 'A:' prefix"
      - MUST be valid UTF-8 encoded plain text
      - Answers SHOULD be factually accurate
      - Category headers SHOULD use square brackets
    commonErrors:
      - "Missing Q: or A: prefixes"
      - Marketing language in answers
      - Incomplete or vague answers
      - Questions that don't match how users ask
      - Outdated information
      - Inconsistency with other AI discovery files

  relationships:
    llms.txt: Services and scope information must be consistent
    ai.txt: Restrictions should be reflected in FAQ answers
    identity.json: Factual details must match

example:
  url: https://www.ai-visibility.org.uk/specifications/examples/faq-ai.txt
  business: Horizon Strategic Consulting

versionHistory:
  - version: "1.8.0"
    date: "2026-05-11"
    changes: "Phase 6 standardisation release. Added /specifications/roadmap/ (theme-pegged forward plan with Active/Next/Future/On hold status flags), /specifications/extensions/ (rules for experimental x- prefixed files and the promotion path), and /specifications/i18n-a11y/ (multi-language publication, locale-tagged identity fields, RTL handling, accessibility of llms.html). Added the Discovery: directive to the robots-ai.txt specification (publishers MAY advertise AI Discovery Files on the same host). Added a formal media-type stance to the HTTP behaviour page (existing IANA types, no bespoke registrations). Expanded the file integrity and signing section on the security and privacy page with four candidate mechanisms, cross-cutting concerns, and interim publisher / consumer guidance. The Discovery: directive is the only normative addition to publisher behaviour; all other additions are forward-looking documentation."
  - version: "1.7.0"
    date: "2026-05-11"
    changes: "Phase 5 standardisation release. Added /specifications/related-standards/ (positioning vs llmstxt.org, IETF AI Preferences, robots.txt, Schema.org, BCP 14, JSON Schema 2020-12, SemVer) and /specifications/implementations/ (public record of conformant implementations, IETF-style). Added an explicit llmstxt.org backward-compatibility statement to the llms.txt specification. Added a formal multi-domain and subdomain scoping rule to both the llms.txt and identity.json specifications (host-scoped files, cross-host identity asserted via sameAs). No normative requirements changed for existing publishers; the new scoping rules formalise behaviour the specification already implied."
  - version: "1.6.0"
    date: "2026-05-11"
    changes: "Phase 4 standardisation release. Added /specifications/processing-model/ (seven-stage algorithm for conformant consumers), /specifications/consumer-guidance/ (what AI systems should do with AI Discovery Files), /specifications/test-vectors/ (canonical test suite framing), and reference-implementation framing on the AI Visibility Checker. No normative requirements changed."
  - version: "1.5.0"
    date: "2026-05-11"
    changes: "Phase 3 standardisation release. Added /specifications/versioning/ (Semantic Versioning 2.0.0 commitments, deprecation timeline, lifecycle), /specifications/governance/ (proposal lifecycle, editorial process, working principles), /specifications/security-privacy/ (trust model, content-injection patterns, GDPR considerations, integrity primitives roadmap), and /specifications/http-behaviour/ (status codes, redirects, soft-404 detection, caching, rate limits). No normative requirements changed."
  - version: "1.4.0"
    date: "2026-05-11"
    changes: "Phase 2 standardisation release. Added formal conformance specification (Essential / Recommended / Complete classes). Published machine-readable registry at /specifications/registry.json, spec meta-schema, and validator-output schema. Introduced versioned JSON Schema URLs (/v1/) alongside unversioned 'latest' aliases. Added optional BCP 47 language declaration field across all applicable AI Discovery Files. No normative requirements changed."
  - version: "1.3.0"
    date: "2026-05-10"
    changes: "Phase 1 standardisation release. Added 'Status of This Document' block (Stable). Normalised normative requirement keywords to uppercase per RFC 2119 and RFC 8174. Added References section linking to /specifications/conventions/ and /licensing/. No normative requirements changed."
  - version: "1.2.0"
    date: "2026-02-25"
    changes: "Added optional URL: field for source links after answers using markdown hyperlink format [Link Text](url). Helps AI assistants provide direct, actionable links when citing answers."
  - version: "1.0.0"
    date: "2026-01-12"
    changes: Initial specification release. Defines faq-ai.txt structure for AI-optimised Q&A content.
