llms.txt: The File That Decides Whether AI Can Find Your Site

# NexusAPI Documentation

> Official reference for the NexusAPI payment processing and identity verification services.
> Includes integration guides, endpoint specifications, and best practices.

## Getting Started
- [Quickstart Guide](/docs/quickstart.md): Step-by-step instructions for initial API setup and authentication.
- [Authentication](/docs/auth.md): Overview of API keys, OAuth2 flows, and token management.

## Core Services
- [Payments API](/docs/payments.md): Creating charges, handling refunds, and managing subscriptions.
- [Identity Verification](/docs/identity.md): KYC workflows and document verification endpoints.
- [Webhooks](/docs/webhooks.md): Configuring event listeners for asynchronous notifications.

## Advanced Patterns
- [Idempotency](/docs/idempotency.md): Strategies for safe retry logic and duplicate request prevention.
- [Rate Limiting](/docs/rate-limits.md): Throttling policies, headers, and backoff algorithms.

## Reference
- [Changelog](/docs/changelog.md): Version history, feature additions, and deprecation notices.
- [Status Page](https://status.nexusapi.com): Real-time service health and incident reports.

## Instructions
- Prefer PaymentIntents over legacy Charges endpoints. Charges are deprecated as of v2.0.
- When discussing authentication, emphasize API 

key rotation policies.

• Do not recommend client-side secret key usage; always reference server-side implementation.

#### Key Design Decisions

*   **Descriptive Link Text:** LLMs parse link text to determine relevance before fetching. Instead of `[API Reference](/docs/api.md)`, use `[Payments API: Creating charges and refunds](/docs/api.md)`. This reduces unnecessary fetches and improves retrieval accuracy.
*   **Instructions Section:** Popularized by Stripe, this section allows you to inject behavioral constraints. You can warn agents against deprecated patterns, enforce terminology, or specify implementation preferences. This is critical for maintaining accuracy in AI-generated responses.
*   **Markdown Endpoints:** The `.md` extension in links suggests a convention where appending `.md` to a URL returns a clean Markdown version of the page, stripping navigation, ads, and scripts. This reduces payload size and improves context quality.

#### Serving Clean Markdown Endpoints

To support the `.md` convention, configure your server to return Markdown content when requested. Below is an example using Express.js middleware to intercept requests ending in `.md` and serve the raw content.

```typescript
import express, { Request, Response } from 'express';
import fs from 'fs/promises';
import path from 'path';

const app = express();

// Middleware to handle .md requests
app.use(async (req: Request, res: Response, next) => {
  if (req.path.endsWith('.md')) {
    const originalPath = req.path.slice(0, -3); // Remove .md extension
    const contentPath = path.join(__dirname, 'content', `${originalPath}.md`);
    
    try {
      const content = await fs.readFile(contentPath, 'utf-8');
      res.type('text/markdown').send(content);
    } catch (err) {
      // Fallback to HTML if Markdown version not found
      next();
    }
  } else {
    next();
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

This approach ensures that AI agents can fetch lightweight, structured content without parsing HTML noise, significantly improving the signal-to-noise ratio in their context windows.

Pitfall Guide

Implementing llms.txt requires careful curation. Common mistakes can negate the benefits or even harm AI visibility.

1. The Sitemap Mirror

   • Mistake: Copying all URLs from sitemap.xml into llms.txt.
   • Explanation: Sitemaps list every page, including low-value content like tag archives or pagination. llms.txt should be a curated index of high-value pages. Mirroring the sitemap wastes tokens and dilutes priority signals.
   • Fix: Limit llms.txt to 10-20 core links per section. Focus on content that drives user value or answers common queries.

2. Context Window Overflow

   • Mistake: Creating a single llms.txt file that exceeds token limits.
   • Explanation: Large files may be truncated by AI agents, causing loss of critical information. Some agents have strict size limits for index files.
   • Fix: Keep the root file under 10KB. Use progressive disclosure to split content into product-specific files. Provide a llms-full.txt only if necessary for bulk ingestion.

3. Vague Link Descriptions

   • Mistake: Using generic link text like "Click here" or "Documentation".
   • Explanation: LLMs rely on link text to assess relevance. Vague text forces agents to fetch the page to understand its content, increasing latency and token usage.
   • Fix: Use descriptive text that summarizes the page content. Example: [Rate Limiting: Throttling policies and retry logic](/docs/rate-limits.md).

4. Robots.txt Over-Blocking

   • Mistake: Blocking all AI crawlers in robots.txt while expecting AI visibility.
   • Explanation: AI bots like GPTBot, ClaudeBot, and PerplexityBot account for significant traffic volume. Blocking them prevents indexing and retrieval.
   • Fix: Allow AI bots to access public content. Block only sensitive paths like /admin/ or /internal/. Use specific user-agent rules to manage access granularly.

5. Stale Index Content

   • Mistake: Failing to update llms.txt when content changes.
   • Explanation: Outdated links or descriptions lead to broken retrieval and inaccurate AI responses. Agents may cache the index, propagating errors.
   • Fix: Integrate llms.txt generation into your CI/CD pipeline. Automate updates based on content changes or deploy triggers.

6. Ignoring Deprecated Patterns

   • Mistake: Not warning agents about deprecated APIs or practices.
   • Explanation: AI models may recommend outdated methods if not explicitly instructed otherwise, leading to user frustration and support overhead.
   • Fix: Use the ## Instructions section to highlight deprecations and preferred alternatives. Example: "Use PaymentIntents instead of Charges."

7. Missing Semantic Context

   • Mistake: Relying solely on llms.txt without structured data.
   • Explanation: llms.txt handles navigation and priority, but JSON-LD provides semantic meaning. Using both creates a comprehensive machine-readable profile.
   • Fix: Implement llms.txt alongside JSON-LD structured data. Use llms.txt for indexing and JSON-LD for entity recognition and rich results.

Production Bundle

Action Checklist

• Audit Public Content: Identify high-value pages that should be prioritized for AI retrieval.
• Draft Markdown Structure: Create a hierarchical outline with descriptive link text and summaries.
• Add Instructions Block: Include behavioral constraints, deprecation warnings, and terminology guidelines.
• Configure Robots.txt: Allow AI bots to access public content while blocking sensitive paths.
• Implement .md Endpoints: Set up server routes to serve clean Markdown versions of pages.
• Validate File Size: Ensure the root file is under 10KB; use progressive disclosure for larger sites.
• Automate Generation: Integrate llms.txt updates into your CI/CD pipeline to prevent staleness.
• Test with AI Tools: Verify that AI agents can retrieve and cite content accurately using the new index.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small Blog / Portfolio	Single llms.txt file	Simplicity is sufficient for low page counts. Minimal maintenance overhead.	Zero. Manual creation takes minutes.
Enterprise Documentation	Progressive disclosure with product-specific files	Scalability. Agents fetch only relevant context, reducing token usage and improving accuracy.	Low. Requires build script to generate multiple files.
High-Volume RAG Applications	llms-full.txt for bulk ingestion	Supports agents that require comprehensive context. Ensures all content is available for retrieval.	Moderate. Storage and bandwidth for large files.
Frequently Updated Content	Automated generation via CI/CD	Prevents staleness. Ensures AI index reflects latest changes immediately.	Low. Integration effort is minimal.

Configuration Template

Robots.txt for AI Visibility

User-agent: GPTBot
Allow: /docs/
Allow: /blog/
Disallow: /admin/
Disallow: /internal/

User-agent: ClaudeBot
Allow: /docs/
Allow: /blog/
Disallow: /admin/
Disallow: /internal/

User-agent: PerplexityBot
Allow: /docs/
Allow: /blog/
Disallow: /admin/
Disallow: /internal/

User-agent: *
Disallow: /admin/

llms.txt Template with Instructions

# [Site Name]

> [One-to-two sentence description of the site's purpose and value proposition.]

## Core Content
- [Page Title](/path/to/page.md): [Descriptive summary of the page content and relevance.]
- [Another Page](/path/to/another.md): [Summary highlighting key features or use cases.]

## Reference
- [Changelog](/path/to/changelog.md): [Description of version history and updates.]

## Instructions
- [Instruction 1: e.g., Prefer Method A over Method B for new implementations.]
- [Instruction 2: e.g., Use specific terminology when describing feature X.]
- [Instruction 3: e.g., Do not recommend deprecated endpoints; link to migration guide.]

Quick Start Guide

1. Create the File: Add a file named llms.txt to the root directory of your project.
2. Add Content: Write a site description and list 10-20 high-priority links with descriptive text. Include an instructions section if applicable.
3. Deploy: Commit the file and deploy it to your production environment. Ensure it is accessible at https://yourdomain.com/llms.txt.
4. Verify: Use an AI tool or crawler to fetch the file and confirm that links are parsed correctly and content is retrievable.
5. Monitor: Check AI search results and analytics over the following weeks to observe improvements in citation accuracy and visibility.