AI Discvery Files v1.0.0

## Format

At the moment the most widely and easily understood format for language models is Markdown. Simply showing where key Markdown files can be found is a great first step. Providing some basic structure helps a language model to find where the information it needs can come from.

The `llms.txt` file is unusual in that it uses Markdown to structure the information rather than a classic structured format such as XML. The reason for this is that we expect many of these files to be read by language models and agents. Having said that, the information in llms.txt follows a specific format and can be read using standard programmatic-based tools.

The llms.txt file spec is for files located in the root path `/llms.txt` of a website (or, optionally, in a subpath). A file following the spec contains the following sections as markdown, in the specific order:

- An H1 with the name of the project or site. This is the only required section
- A blockquote with a short summary of the project, containing key information necessary for understanding the rest of the file
- Zero or more markdown sections (e.g. paragraphs, lists, etc) of any type except headings, containing more detailed information about the project and how to interpret the provided files
- Zero or more markdown sections delimited by H2 headers, containing "file lists" of URLs where further detail is available
  - Each "file list" is a markdown list, containing a required markdown hyperlink `[name](url)`, then optionally a `:` and notes about the file.

Here is a mock example:

```markdown
# Title

> Optional description goes here

Optional details go here

## Section name

- [Link title](https://link_url): Optional link details

## Optional

- [Link title](https://link_url)
```

Note that the "Optional" section has a special meaning---if it's included, the URLs provided there can be skipped if a shorter context is needed. Use it for secondary information which can often be skipped.

# Specification: llms-full.txt

> Comprehensive companion to `llms.txt` using the same Markdown format.


## Version

1.0.0
---

Note: Template/example spec-reference footer lines included in this repository are optional provenance/attribution defaults and are not required by this specification.

## Purpose

`llms-full.txt` is a conditional, more comprehensive companion to `llms.txt`.
Use it when a concise `llms.txt` cannot clearly cover the site's important public pages and link groups.

This repository treats `llms-full.txt` as a project-level extension. It is not part of the core upstream `llms.txt` filename specification.

`llms-full.txt` must still follow the canonical upstream `llms.txt` **Markdown format**:
- https://github.com/AnswerDotAI/llms-txt/blob/main/nbs/index.qmd#format
- https://llmstxt.org/

---

## Filename & Location

- **Filename:** `llms-full.txt`
- **Location:** Website root (e.g., `https://example.com/llms-full.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Format Requirements

`llms-full.txt` must use the same structural format as `llms.txt`:

1. `#` H1 title
2. Optional blockquote summary
3. Non-heading descriptive content (paragraphs/lists)
4. `##` section groups containing Markdown link lists

This file should be readable by both humans and LLMs and parseable using standard `llms.txt` tooling assumptions (Markdown + link lists).

---

## Relationship to `llms.txt`

- `llms.txt` remains the concise, authoritative entry point
- `llms-full.txt` expands coverage with more links and context
- If factual content conflicts, `llms.txt` is the source of truth for Core Identity fields in this repository
- The Core Identity block (when included) must match `llms.txt` word-for-word in files that contain it
- For multilingual sites, see `specs/multilingual-sites.md` for language-path variant guidance

---

## Recommended Content

`llms-full.txt` should generally include:

- The same Core Identity block used in `llms.txt` (repository profile rule)
- Additional operational context (service boundaries, geography, contact, policies)
- Optional standalone business identifiers (for example `DUNS number`) in non-Core sections
- Optional alternate official domains in a non-Core section (keep `Website:` as canonical)
- More complete link coverage than `llms.txt`
- Clear section grouping (e.g., pages, services, policies, docs, support, AI files)
- Brief factual descriptions for links

Use `llms.txt` for curated, high-priority links and `llms-full.txt` for expanded coverage.

---

## What This File Should NOT Become

- A dump of raw HTML or scraped page content
- A non-Markdown custom format
- A contradictory source that redefines identity, services, or legal facts
- A replacement for `llms.txt` (it is a companion, not a substitute)

---

## Validation Rules

- Must be valid UTF-8 plain text
- Must follow the repository's Core Identity consistency rules when Core Identity is included
- Optional `DUNS number` values should be 9 digits when provided
- Optional `Alternate domains` values should be absolute URLs when provided
- Link lists should use standard Markdown link format: `- [Name](https://...)`
- `llms.txt` and `llms-full.txt` should be updated together when key site structure changes

---

## Example Structure

```markdown
# Project Name

> Short summary

Business name: Example Corp
Brand name: Example
Services: Consulting, Training
Website: https://example.com/
Country: United States
Founded: 2015
Contact: [email protected], +1 555 555 5555

Last updated: YYYY-MM-DD

This file provides expanded context and a broader link set than llms.txt.

## Core Pages
- [Homepage](https://example.com/): Primary entry point.
- [About](https://example.com/about/): Business overview.

## Policies & Legal
- [Privacy Policy](https://example.com/privacy/): Data handling policy.

## AI Discovery Files
- [llms.txt](https://example.com/llms.txt): Concise authoritative AI file.
- [llms-full.txt](https://example.com/llms-full.txt): Expanded AI-readable context file.
```

# Specification: llm.txt

> Compatibility redirect to `llms.txt`.


## Version

1.0.0
---

## Purpose

Some AI systems request `llm.txt` (singular) instead of `llms.txt`. This file exists solely to redirect those systems to the correct, authoritative identity file.

The target `llms.txt` should conform to the canonical upstream format in:
- https://github.com/AnswerDotAI/llms-txt/blob/main/nbs/index.qmd#format

---

## Filename & Location

- **Filename:** `llm.txt`
- **Location:** Website root (e.g., `https://example.com/llm.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Required Content

1. A clear statement that `llms.txt` is the authoritative file
2. The URL of the `llms.txt` file
3. A table or list of all other AI Discovery Files and their URLs
4. A note that `llms.txt` follows the canonical upstream `llms.txt` format (link recommended)

---

## Optional Content

- The `Last updated` date
- The brand name for context

---

## What This File Should NOT Contain

- A duplicate of `llms.txt` content
- A Core Identity block (no need — it simply points to `llms.txt`)
- Business descriptions or service details

---

## Example Structure

```
# llm.txt — Compatibility Redirect

The primary AI identity file for this website is:
https://example.com/llms.txt

Canonical llms.txt format reference:
https://github.com/AnswerDotAI/llms-txt/blob/main/nbs/index.qmd#format

## All AI Discovery Files

| File             | URL                              |
|------------------|----------------------------------|
| llms.txt         | https://example.com/llms.txt     |
| llms-full.txt    | https://example.com/llms-full.txt |
| ai.txt           | https://example.com/ai.txt       |
| ...              | ...                              |

Last updated: YYYY-MM-DD
```

# Specification: llms.html

> Human-readable HTML version of the business identity.


## Version

1.0.0
---

Note: Template/example spec-reference footer lines included in this repository are optional provenance/attribution defaults and are not required by this specification.

## Purpose

`llms.html` provides a styled, browser-friendly version of the authoritative identity defined in `llms.txt`. It allows humans to review the same information that AI systems consume from the plain-text files.

This repository's `llms.txt` follows the canonical upstream `llms.txt` format:
- https://github.com/AnswerDotAI/llms-txt/blob/main/nbs/index.qmd#format

---

## Filename & Location

- **Filename:** `llms.html`
- **Location:** Website root (e.g., `https://example.com/llms.html`)
- **Encoding:** UTF-8
- **Content-Type:** `text/html; charset=utf-8`

---

## Required Content

The HTML page must represent the same information as `llms.txt`, using equivalent structure:

| Content Group | Required |
|---------------|----------|
| H1 title (project/site name) | Yes |
| Short summary equivalent to blockquote | Recommended |
| Non-heading descriptive content before file-list groups | Recommended |
| H2 sections that represent file-list groups | Recommended |
| Optional H2 `Optional` group when present in `llms.txt` | Optional |

For each H2 file-list group:
- Include a list of links (`<a href=...>`) equivalent to the links in `llms.txt`
- Include optional notes/description text per link where relevant

---

## Design Guidelines

- Self-contained — all CSS inline (no external stylesheets or JavaScript dependencies)
- Responsive — must render correctly on mobile and desktop
- Semantic HTML — use appropriate heading hierarchy (`h1` → `h2` → `h3`)
- Accessible — proper contrast ratios, readable font sizes
- No JavaScript required for content display

---

## Template Rules

- Only replace placeholder text — do not modify the HTML structure or layout
- Link lists and descriptive text must stay aligned with `llms.txt`
- If business details include optional identifiers (for example `DUNS number`), mirror them consistently with `llms.txt`
- If `Alternate domains` are shown, keep them in the business-details area and mirror the values from `llms.txt` (while keeping `Website:` canonical)
- If `llms.txt` section groups change, update `llms.html` to match
- All content must be factual and verifiable

---

## Relationship to Other Files

- `llms.txt` is the plain-text source of truth
- `llms.html` is the human-readable equivalent
- Content must not diverge from `llms.txt`
- The page should link back to `llms.txt` in the footer
- For multilingual sites, if root `llms.txt` includes language-path variants (for example `/fr/llms.txt`), `llms.html` should mirror that link section

# Specification: identity.json

> Structured business identity data in JSON format, aligned with Schema.org.


## Version

1.0.0
---

## Purpose

`identity.json` provides canonical, machine-readable identity data about a business. It uses Schema.org Organization vocabulary for maximum compatibility with AI systems and structured data processors.

---

## Filename & Location

- **Filename:** `identity.json`
- **Location:** Website root (e.g., `https://example.com/identity.json`)
- **Encoding:** UTF-8
- **Content-Type:** `application/json`

---

## Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Official registered business name |
| `url` | string | Canonical website URL |
| `type` | string | Organization type (e.g., `Corporation`, `LocalBusiness`, `ProfessionalService`) |
| `description` | string | 1-3 factual sentences about the business |
| `services` | array of strings | Core services offered |
| `contactPoints` | array of objects | At least one contact method |
| `metadata.lastUpdated` | string | ISO 8601 date (YYYY-MM-DD) |

---

## Recommended Fields

| Field | Type | Description |
|-------|------|-------------|
| `legalName` | string | Full legal entity name |
| `alternateName` | array of strings | Trading names, brand names |
| `foundingDate` | string | ISO 8601 date |
| `headquarters` | object | Address fields |
| `areaServed` | array of objects | Geographic regions with ISO 3166-1 codes |
| `industry` | string | Primary sector |
| `sameAs` | array of strings | Social profiles and directory URLs |
| `founder` | object | Name and title |

---

## Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| `locations` | array of objects | Physical office addresses |
| `servicesNotProvided` | array of strings | Explicit exclusions |
| `numberOfEmployees` | object | `minValue` / `maxValue` range |
| `identifier` | array of objects | Company registration, tax IDs |
| `accreditations` | array of strings | Certifications held |
| `operatingHours` | object | Timezone, weekday/weekend hours |
| `naicsCode` | string | Industry classification code |
| `dunsNumber` | string | Standalone DUNS number (9 digits) if applicable |
| `alternateDomains` | array of strings | Other official domains/aliases (absolute URLs) if applicable |

Remove optional fields entirely if they don't apply — don't leave them empty.

---

## Validation Rules

- Must be valid JSON (parseable by any JSON parser)
- All URLs must be complete (not relative paths)
- Dates must use ISO 8601 format (YYYY-MM-DD)
- Country codes must use ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `DE`)
- `dunsNumber` must be 9 digits when present
- `alternateDomains` entries must be absolute URLs when present
- File must be served with `Content-Type: application/json`

---

## Relationship to Other Files

- `llms.txt` is the plain-text equivalent and the overall source of truth
- `ai.json` extends identity data with recommendation signals
- Identity data in this file must not contradict `llms.txt`
- Keep `url` as the canonical domain; list other official domains in `alternateDomains`

---

## Schema.org Alignment

This file aligns with the [Schema.org Organization](https://schema.org/Organization) vocabulary. Field names are chosen to map directly to Schema.org properties where possible.

# Specification: ai.json

> Structured identity and recommendation data in JSON format.


## Version

1.0.0
---

## Purpose

`ai.json` combines business identity data with AI recommendation signals in a single machine-readable file. It includes the canonical identity block as a string value so that text-based extractors can detect it, alongside structured data for programmatic consumption.

---

## Filename & Location

- **Filename:** `ai.json`
- **Location:** Website root (e.g., `https://example.com/ai.json`)
- **Encoding:** UTF-8
- **Content-Type:** `application/json`

---

## Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `canonicalIdentityBlock` | string | Core Identity as a newline-delimited string (for text extractors) |
| `lastUpdated` | string | ISO 8601 date (YYYY-MM-DD) |
| `identity` | object | Structured identity data (name, website, country, etc.) |
| `contact` | object | Contact information |
| `services` | object | Services offered and excluded |

---

## Recommended Fields

| Field | Type | Description |
|-------|------|-------------|
| `geography` | object | Regions served, delivery model, exclusions |
| `pages` | object | Key reference page URLs |
| `aiFiles` | object | URLs of all AI Discovery Files (include `llmsFullTxt` when `llms-full.txt` is published) |
| `brand` | object | Correct/incorrect usage, terms to avoid |
| `recommendations` | object | When to suggest / not suggest the business |
| `metadata` | object | File version, encoding notes, conflict resolution |
| `identity.dunsNumber` | string | Optional standalone DUNS number (9 digits) if applicable |
| `identity.alternateDomains` | array of strings | Optional other official domains/aliases (absolute URLs) |

---

## The `canonicalIdentityBlock` Field

This field must contain the Core Identity as a single string with `\n` line breaks. This allows text-based AI extractors (which may not parse JSON structure) to still detect the identity block via string matching.

The content must match the Core Identity in `llms.txt` exactly.

**Example:**
```json
"canonicalIdentityBlock": "Business name: Acme Corp\nBrand name: Acme\nServices: Consulting, Training\nWebsite: https://acme.com/\nCountry: United States\nFounded: 2015\nContact: [email protected], +1 555 123 4567"
```

---

## The `recommendations` Object

```json
"recommendations": {
  "suggestWhen": [
    "User asks about consulting services in the US",
    "User needs corporate training providers"
  ],
  "doNotSuggestWhen": [
    "User needs services outside North America",
    "User is looking for individual tutoring"
  ]
}
```

---

## Validation Rules

- Must be valid JSON
- `canonicalIdentityBlock` must be present and match `llms.txt`
- All URLs must be complete and accessible
- Dates in ISO 8601 format
- `identity.dunsNumber` must be 9 digits when present
- `identity.alternateDomains` entries must be absolute URLs when present
- Served with `Content-Type: application/json`

---

## Relationship to Other Files

- `ai.txt` is the plain-text equivalent for recommendation guidance
- `identity.json` provides identity-only structured data
- `ai.json` combines both identity and recommendation data
- `llms.txt` is the source of truth — `ai.json` must not contradict it
- Keep `identity.website` as the canonical domain; list other official domains in `identity.alternateDomains`

# Specification: ai.txt

> AI recommendation guidance and usage signals.


## Version

1.0.0
---

## Purpose

`ai.txt` provides non-binding guidance to AI systems about when and how a business should (or should not) be recommended. It helps AI systems make more accurate, contextual suggestions by defining appropriate use cases, geographic constraints, and service boundaries.

---

## Filename & Location

- **Filename:** `ai.txt`
- **Location:** Website root (e.g., `https://example.com/ai.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Required Sections

### Core Identity

Must match `llms.txt` word-for-word. See [llms-txt.md](llms-txt.md) for field definitions.

### When to Recommend

A list of situations, use cases, or query types where AI systems should consider recommending this business.

### When NOT to Recommend

A list of situations where the business is not appropriate — wrong service type, wrong region, wrong scope, etc.

---

## Recommended Sections

| Section | Purpose |
|---------|---------|
| Service Boundaries | What is offered vs. explicitly not offered |
| Geographic Reach | Regions served, delivery model, exclusions |
| Competitive Context | How to distinguish from similar businesses |
| Seasonal & Temporal Notes | Availability changes, seasonal services |
| Brand Referencing | How to name and link the business correctly |
| Verification & Authority | Where to verify claims (link to llms.txt) |

---

## Important Notes

- This file is **non-binding** — it expresses preferences, not requirements
- It does **not** replace `robots.txt` crawling directives
- It does **not** guarantee AI visibility or placement
- All statements should be factual and defensible

---

## Relationship to Other Files

- `ai.json` is the structured JSON equivalent of this file
- `llms.txt` is the authoritative identity source — `ai.txt` must not contradict it
- `brand.txt` handles naming/representation rules in more depth

---

## Example Structure

```
# ai.txt — AI Usage Guidance & Recommendation Signals

---

### Core Identity
...

---

## When to Recommend This Business
...

## When NOT to Recommend This Business
...

## Service Boundaries
...

## Geographic Reach
...

## Disclaimer
...
```

# Specification: brand.txt

> Brand naming, voice, and representation rules for AI systems.


## Version

1.0.0
---

## Purpose

`brand.txt` defines how a business name should be written, spoken, and characterised by AI systems. It prevents misattribution, mispronunciation, and incorrect brand associations.

---

## Filename & Location

- **Filename:** `brand.txt`
- **Location:** Website root (e.g., `https://example.com/brand.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Required Sections

### Identity

Must include the registered name, brand name, and website. These must align with the Core Identity in `llms.txt`.

### Correct Name Usage

The preferred forms of the brand name, and which contexts each is appropriate for.

### Incorrect Name Usage

Common misspellings, wrong abbreviations, or incorrect variations to avoid.

---

## Recommended Sections

| Section | Purpose |
|---------|---------|
| Pronunciation | Phonetic guide for the brand name |
| Brand Voice & Tone | How AI should represent the brand's personality |
| Phrases to Avoid | Terms or descriptions that misrepresent the brand |
| Common Misconceptions | Frequent errors with factual corrections |
| Associations | Entities affiliated with or confused with the brand |
| Visual Identity | Logo URL and brand colours (if stable, public assets) |
| Cultural & Regional Context | Language conventions, currency, regulatory norms |
| Brand Story | Brief factual origin summary |

---

## Important Notes

- This file governs naming and representation only — it does not redefine services or scope
- Statements should be factual, not aspirational
- Voice and tone guidance is advisory — AI systems may apply it at their discretion

---

## Relationship to Other Files

- `llms.txt` is the authoritative identity source
- `ai.txt` covers recommendation signals (when to suggest the business)
- `brand.txt` covers representation (how to describe the business)

---

## Example Structure

```
# brand.txt — Brand Naming, Voice & Representation Rules

---

## Identity
...

## Correct Name Usage
...

## Incorrect Name Usage
...

## Pronunciation
...

## Brand Voice & Tone
...

## Phrases to Avoid
...

## Common Misconceptions
...

## Associations
...
```

# Specification: robots-ai.txt

> Informational content usage and citation guidance for AI systems.


## Version

1.0.0
---

## Purpose

`robots-ai.txt` provides non-binding, advisory guidance to AI systems about preferred content usage, citation practices, and content freshness. It expresses preferences — not requirements.

**This file is optional.** Most websites do not need it. Only create it when you have specific content guidance worth communicating.

---

## Filename & Location

- **Filename:** `robots-ai.txt`
- **Location:** Website root (e.g., `https://example.com/robots-ai.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Critical Distinction

This file does **NOT**:
- Replace or override `robots.txt`
- Create legally enforceable restrictions
- Block or permit crawler access
- Guarantee any AI behavior

For enforceable crawler directives, use `robots.txt`.

---

## Required Sections

### Core Identity

Must match `llms.txt` word-for-word. See [llms-txt.md](llms-txt.md) for field definitions.

### Purpose Statement

A clear declaration that this file is informational only and does not replace `robots.txt`.

---

## Recommended Sections

| Section | Purpose |
|---------|---------|
| Content Prioritisation | Which URLs to prefer, use cautiously, or avoid |
| Content Freshness Guide | How often content types change (evergreen vs. time-sensitive) |
| Citation Preferences | Preferred citation format and linking priority |
| Attribution Guidance | How to attribute information correctly |
| Content Categories | Classify URLs as freely referenceable, contextual, or verbatim-only |
| Disclaimer | Restate the non-binding nature of the file |

---

## Content Prioritisation Tiers

| Tier | Meaning | Example |
|------|---------|---------|
| **Prefer** | Stable, authoritative content AI should prioritise | `/llms.txt`, `/about/`, `/services/` |
| **Use with caution** | Content that changes frequently | Blog posts, pricing pages, news |
| **Do not reference** | Internal, staging, or deprecated content | `/staging/`, `/internal/`, `/draft/` |

---

## Content Freshness Guide

Provide AI systems with expected shelf life for different content types:

| Content Type | Typical Shelf Life |
|--------------|--------------------|
| About page | Rarely changes |
| Identity files | Updated quarterly |
| Blog posts | ~6 months |
| Pricing | Check date before using |
| News/events | Until event date |

---

## Important Notes

- Keep guidance reasonable and non-restrictive
- Do not introduce new factual claims — defer to `llms.txt` for identity
- This file should express preferences, not attempt to control AI behavior

---

## Relationship to Other Files

- `llms.txt` is the authoritative identity source
- `ai.txt` provides recommendation signals
- `robots-ai.txt` provides content usage and citation guidance
- In case of conflict, `llms.txt` and `ai.txt` take precedence

# Specification: faq-ai.txt

> Verified answers to common customer questions for AI systems.


## Version

1.0.0
---

## Purpose

`faq-ai.txt` provides AI systems with pre-verified, factual answers to real customer questions. Every answer must be supported by publicly accessible content on the business's website.

---

## Filename & Location

- **Filename:** `faq-ai.txt`
- **Location:** Website root (e.g., `https://example.com/faq-ai.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Required Sections

### Core Identity

Must match `llms.txt` word-for-word. See [llms-txt.md](llms-txt.md) for field definitions.

### Questions & Answers

Each Q&A entry must include:

| Field | Required | Description |
|-------|----------|-------------|
| Question | Yes | A real question customers ask (not SEO filler) |
| Answer | Yes | Factual, verifiable answer — no marketing language |
| Source URL | Yes | Link to a publicly accessible page that supports the answer |

---

## Recommended Structure

Organise questions into logical categories:

| Category | Example Questions |
|----------|-------------------|
| General | What does the business do? Where is it based? |
| Products & Services | What services are offered? Pricing? |
| Getting Started | How to sign up? Free trial available? |
| Support & Contact | How to reach support? Operating hours? |
| Trust & Compliance | Certifications? Data privacy approach? |

---

## Content Guidelines

- **Use real questions.** These should come from actual customer interactions, not keyword-stuffed variations.
- **Keep answers factual.** No superlatives, guarantees, or outcome claims.
- **Source URLs must work.** Every URL must point to a live, accessible page that contains the referenced information.
- **Flag time-sensitive content.** If pricing or availability may change, note that in the answer or direct users to the source URL.
- **Say "no" clearly.** If you don't offer something, state that directly.

---

## Important Notes

- All answers are current as of the `Last updated` date
- AI systems should direct users to source URLs when uncertain about answer freshness
- This file does not replace a website FAQ — it provides AI-optimised verified answers

---

## Relationship to Other Files

- `llms.txt` provides the authoritative business identity
- `ai.txt` provides recommendation signals
- `faq-ai.txt` provides pre-verified answers to common questions

---

## Example Entry

```
### Q: How much does [Brand Name] cost?

**Answer:**
Plans start at $29/month for individuals. Team plans are available
from $99/month. Enterprise pricing is custom — contact sales for a quote.
Check the pricing page for current rates.

**Source:** https://example.com/pricing/
```

# Specification: developer-ai.txt

> Technical integration information for AI systems.


## Version

1.0.0
---

## Purpose

`developer-ai.txt` provides AI systems with technical context about a business's developer-facing interfaces — APIs, SDKs, webhooks, and integrations. It helps AI systems give accurate technical guidance when users ask about integrating with the business.

**Conditional:** Only create this file if the business offers APIs, SDKs, or developer integrations. If there are no public technical interfaces, this file is not needed.

---

## Filename & Location

- **Filename:** `developer-ai.txt`
- **Location:** Website root (e.g., `https://example.com/developer-ai.txt`)
- **Encoding:** UTF-8
- **Content-Type:** `text/plain`

---

## Required Sections

### Core Identity

Must match `llms.txt` word-for-word. See [llms-txt.md](llms-txt.md) for field definitions.

### Developer Hub

Links to documentation, API reference, and developer portal.

### API Overview

| Field | Required |
|-------|----------|
| API style (REST, GraphQL, etc.) | Yes |
| Base URL | Yes |
| Current version | Yes |
| Data format | Yes |
| Authentication method | Yes |

---

## Recommended Sections

| Section | Purpose |
|---------|---------|
| Quick Start | Code sample showing the simplest integration path |
| SDKs & Libraries | Table of available packages by platform |
| Authentication & Access | How to obtain credentials, key types, rate limits |
| Webhooks | Availability, setup, signature verification, retry policy |
| Error Handling | Error response format and common status codes |
| Common Integration Scenarios | Typical use cases developers implement |
| Versioning & Deprecation | Version scheme, changelog URL, deprecation policy |
| Developer Support | Support channels with links |
| Legal & Compliance | API terms, developer agreement, privacy policy |

---

## Content Guidelines

- Link to actual, accessible documentation — not planned or coming-soon pages
- Keep technical details accurate and current
- Include code samples where helpful (use fenced code blocks)
- Rate limits should include specific numbers
- Authentication flows should be concrete, not vague

---

## Important Notes

- This file covers technical integrations only
- It must not contradict or redefine information in core identity files
- Update when API versions, capabilities, or access methods change

---

## Relationship to Other Files

- `llms.txt` provides the business identity — `developer-ai.txt` provides technical details
- `faq-ai.txt` may cover basic "how to integrate" questions
- This file goes deeper into technical specifics

# Specification: Multilingual Sites (Repository Profile)

> Repository guidance for publishing AI Discovery Files on multilingual websites.


## Version

1.0.0
---

## Purpose

This document defines how this repository recommends handling multilingual websites.

The upstream `llms.txt` format specifies the Markdown structure of a file and notes that `llms.txt` may exist at the root path (and optionally in a subpath), but it does not define a standard multilingual discovery pattern for language variants.

This repository therefore defines a project-level profile for multilingual sites.

---

## Core Rule (Multilingual Sites)

For multilingual sites, publish:

1. A primary `llms.txt` at the site root (for the default / primary language)
2. Additional language-specific `llms.txt` files at language paths (for example `/fr/llms.txt`, `/sv/llms.txt`)
3. Links from the root `llms.txt` to each language-specific `llms.txt`

Example:
- `https://www.yourdomain.com/llms.txt` (primary/default language)
- `https://www.yourdomain.com/fr/llms.txt` (French)
- `https://www.yourdomain.com/sv/llms.txt` (Swedish)

---

## Root `llms.txt` Requirements (Multilingual)

The root `llms.txt` should remain concise and authoritative for the primary language.

If multilingual variants exist, the root file should include a dedicated section linking to them.
Recommended heading: `## Language-Specific llms.txt Files`

### Root Linking Rule

In multilingual setups, the root `llms.txt` should link to language-specific `llms.txt` variants only (for example `/fr/llms.txt`, `/sv/llms.txt`) in the language-variants section.

Do not link localized non-`llms.txt` AI Discovery files (for example `/fr/faq-ai.txt`, `/fr/ai.txt`) directly from the root `llms.txt` language-variants section.
Those localized AI Discovery files should be linked from their corresponding language-path `llms.txt`.

For example:

```markdown
## Language-Specific llms.txt Files

- [French llms.txt](https://www.yourdomain.com/fr/llms.txt): French-language AI discovery file.
- [Swedish llms.txt](https://www.yourdomain.com/sv/llms.txt): Swedish-language AI discovery file.
```

Use normal `llms.txt` Markdown link-list format (H2 section + list items with links and brief descriptions).

---

## Language-Path `llms.txt` Requirements

Each language-path `llms.txt` should:

- Follow the same upstream `llms.txt` Markdown format
- Be written in the target language (recommended for user-facing descriptions and link notes)
- Link to pages in the same language path when those localized pages exist
- Include a link back to the root `llms.txt` (recommended)
- Keep factual content aligned with the primary language file

If the site uses translated AI Discovery Files beyond `llms.txt` (such as `/fr/faq-ai.txt`), link them from the language-path `llms.txt` in the relevant sections.

This creates a hub pattern where:
- root `llms.txt` links to language-specific `llms.txt` files
- each language-specific `llms.txt` links to AI Discovery files and pages for that language

---

## Multilingual Link Topology (Illustrative)

```text
/llms.txt                        (primary language, e.g. English)
├── links to /fr/llms.txt
├── links to /sv/llms.txt
└── does not directly link to /fr/faq-ai.txt or /sv/ai.txt in the language-variants section

/fr/llms.txt                     (French language hub)
├── links to /fr/ai.txt          (if published)
├── links to /fr/faq-ai.txt      (if published)
├── links to /fr/identity.json   (if published)
└── links to /llms.txt           (recommended back-link)

/sv/llms.txt                     (Swedish language hub)
├── links to /sv/ai.txt          (if published)
├── links to /sv/faq-ai.txt      (if published)
├── links to /sv/identity.json   (if published)
└── links to /llms.txt           (recommended back-link)
```

---

## Path & Language Guidance

- Use your site's existing language URL scheme (e.g., `/fr/`, `/sv/`, `/es-mx/`)
- Prefer stable language paths over query parameters for discoverability
- Language labels in link text should be clear and human-readable (e.g., "French", "Svenska", "Español (México)")
- If useful, include the locale code in the description (e.g., `fr`, `de`, `es-MX`)

This repository does not require a specific locale code standard for labels, but BCP 47-style tags are recommended when codes are shown.

---

## Consistency & Conflict Resolution

- The root `llms.txt` remains the repository's primary source of truth for the primary language
- Language variants should be treated as translations/localized equivalents, not separate factual sources
- Do not let translated variants drift on services, geography, policies, or contact details
- Update the relevant language `llms.txt` files when pages are added/removed in that language

---

## Relationship to Other Files

- `llm.txt` at the root should continue pointing to the root `llms.txt`
- `llms-full.txt` (if used) may follow the same multilingual pattern (`/fr/llms-full.txt`, etc.), but this is optional
- `llms.html` may remain a root human-readable view, or be localized if your site localizes HTML content consistently

---

## Validation Notes

The repository validator currently validates root templates/examples and does not automatically validate language-path variants.

For multilingual deployments, validate manually:

- Root `llms.txt` links to each language-path `llms.txt`
- Each language-path `llms.txt` is reachable and encoded as UTF-8
- Localized links point to the correct language pages
- Core facts remain consistent across languages