aptos-labs · gregnazario · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,7 +4,11 @@ This document provides essential guidelines for AI agents working on the Aptos D
 
 ## Project Overview
 
-This repository contains the official Aptos Developer Documentation, built using [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). The documentation is available in multiple languages including English, Spanish (es), and Chinese (zh).
+This repository contains the official Aptos Developer Documentation, built using [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). The documentation is available in English and Chinese (zh).
+
+## Machine-readable documentation for agents
+
+Production docs are indexed for LLMs and coding agents at [https://aptos.dev/llms.txt](https://aptos.dev/llms.txt) (same content as [https://aptos.dev/.well-known/llms.txt](https://aptos.dev/.well-known/llms.txt)). For IDE access to Aptos APIs and on-chain data, use the Aptos MCP server (`npx @aptos-labs/aptos-mcp`); see the live [AI tools](https://aptos.dev/build/ai) page.
 
 ## Development Setup
 
@@ -38,7 +42,6 @@ pnpm dev            # Start development server (http://localhost:4321)
 src/
 ├── content/
 │   ├── docs/           # Main English documentation
-│   │   ├── es/         # Spanish translations
 │   │   └── zh/         # Chinese translations
 │   ├── i18n/           # UI translations
 │   └── nav/            # Sidebar translations
@@ -62,18 +65,20 @@ Run these commands after making changes to ensure code quality.
 
 ### 2. Translation Requirements
 
-**All documentation changes must be translated and verified in both Chinese and Spanish versions.**
+**All documentation changes must be translated and verified in the Chinese version.**
 
 - **English docs:** `src/content/docs/`
-- **Spanish docs:** `src/content/docs/es/`
 - **Chinese docs:** `src/content/docs/zh/`
 
 When modifying documentation:
 
 1. Make the change in the English version first
-2. Create or update the corresponding Spanish translation in `es/`
-3. Create or update the corresponding Chinese translation in `zh/`
-4. Ensure all internal links use the correct language prefix (e.g., `/es/network/` for Spanish)
+2. Create or update the corresponding Chinese translation in `zh/`
+3. Ensure all internal links use the correct language prefix (e.g., `/zh/network/` for Chinese)
+
+**No Spanish documentation tree:** Do not add pages under `src/content/docs/es/`. The site does not ship Spanish MDX/Markdown docs.
+
+**Translated PDFs and external assets:** You may still link official non-English files when appropriate—for example the Spanish white paper PDF (`aptos-whitepaper_es.pdf`) from the [Aptos white paper](/network/blockchain/aptos-white-paper) page alongside other language PDFs.
 
 ### 3. Commit Message Requirements
 
@@ -101,7 +106,7 @@ Example:
 docs: add glossary entry for BlockSTM
 
 Added definition and example for BlockSTM parallel execution engine.
-Updated Spanish and Chinese translations accordingly.
+Updated Chinese translation accordingly.
 ```
 
 ### 4. Grammar and Style
@@ -121,7 +126,6 @@ Updated Spanish and Chinese translations accordingly.
 The glossary is located at:
 
 - **English:** `src/content/docs/network/glossary.mdx`
-- **Spanish:** `src/content/docs/es/network/glossary.mdx`
 - **Chinese:** `src/content/docs/zh/network/glossary.mdx`
 
 When adding a new term to the glossary:
@@ -160,7 +164,6 @@ sidebar:
 Use relative paths without the file extension:
 
 - English: `/network/blockchain/accounts`
-- Spanish: `/es/network/blockchain/accounts`
 - Chinese: `/zh/network/blockchain/accounts`
 
 ## Content Guidelines
@@ -190,18 +193,16 @@ module example::hello {
 
 1. Create the MDX file in the appropriate directory
 2. Add frontmatter with title and description
-3. Create Spanish translation in `es/` subdirectory
-4. Create Chinese translation in `zh/` subdirectory
-5. Update sidebar configuration if needed (`astro.sidebar.ts`)
-6. Run `pnpm lint` and `pnpm format`
+3. Create Chinese translation in `zh/` subdirectory
+4. Update sidebar configuration if needed (`astro.sidebar.ts`)
+5. Run `pnpm lint` and `pnpm format`
 
 ### Updating the Glossary
 
 1. Add the term to `src/content/docs/network/glossary.mdx`
-2. Add Spanish translation to `src/content/docs/es/network/glossary.mdx`
-3. Add Chinese translation to `src/content/docs/zh/network/glossary.mdx`
-4. Ensure alphabetical ordering within each section
-5. Include definition, examples, and links to related content
+2. Add Chinese translation to `src/content/docs/zh/network/glossary.mdx`
+3. Ensure alphabetical ordering within each section
+4. Include definition, examples, and links to related content
 
 ## Resources
 

diff --git a/astro.config.mjs b/astro.config.mjs
@@ -139,6 +139,11 @@ export default defineConfig({
             // Exclude autogenerated content and non-translatable static resources
             const excludePaths = ["/rest-api", "/move-reference", "/gas-profiling", "/scripts"];
 
+            // Plain-text LLM exports (injected routes; no HTML page for the validator to crawl)
+            if (link.includes("/llms-small.txt") || link.includes("/llms-full.txt")) {
+              return true;
+            }
+
             // Exclude specific problematic links from external move-reference content
             const excludeLinks = [
               "https://aptos.dev/move/book/SUMMARY",
@@ -151,42 +156,10 @@ export default defineConfig({
             );
           },
         }),
+        // Registers /llms.txt, /llms-small.txt, /llms-full.txt routes; local handlers override output
+        // (see src/integrations/llms-txt-index.ts). Curation lives in src/lib/llms-curated-ids.ts + src/lib/llms.ts.
         starlightLlmsTxt({
           rawContent: true,
-          description:
-            "Developer documentation for the Aptos blockchain — Move smart contracts, SDKs, APIs, indexer, node operations, and AI tools.",
-          details: [
-            "For AI coding tools, install the Aptos MCP server: `npx @aptos-labs/aptos-mcp`",
-            "It gives your IDE direct access to Aptos APIs, on-chain data, and Move contract helpers.",
-            "See <https://aptos.dev/build/ai> for setup guides (Claude Code, Cursor, and more).",
-          ].join("\n"),
-          optionalLinks: [
-            {
-              label: "Aptos MCP Server",
-              url: "https://www.npmjs.com/package/@aptos-labs/aptos-mcp",
-              description: "MCP server for AI coding tools",
-            },
-            {
-              label: "Aptos GitHub",
-              url: "https://github.com/aptos-labs",
-              description: "Official source code repositories",
-            },
-          ],
-          promote: [
-            "index*",
-            "get-started",
-            "network/glossary",
-            "build/smart-contracts*",
-            "network/blockchain*",
-            "build/sdks*",
-            "build/apis*",
-            "build/cli*",
-            "build/indexer*",
-            "build/guides*",
-            "build/ai*",
-          ],
-          demote: ["404"],
-          exclude: ["404"],
         }),
         ...(hasAlgoliaConfig
           ? [
@@ -217,9 +190,9 @@ export default defineConfig({
       sidebar,
       customCss: ["./src/styles/global.css", "katex/dist/katex.min.css"],
     }),
-    // Override the starlight-llms-txt plugin's /llms.txt index with a structured
-    // version that lists page titles, descriptions, and per-page .md URLs.
-    // Must be after Starlight so our injected route takes priority.
+    // Override the starlight-llms-txt plugin's generated llms routes with
+    // local handlers so we can curate the index and tune the small/full exports.
+    // Must be after Starlight so our injected routes take priority.
     llmsTxtIndex(),
     sitemap({
       serialize(item) {

diff --git a/public/robots.txt b/public/robots.txt
@@ -1,13 +1,34 @@
 User-agent: Algolia Crawler
 Allow: /
 
+# OpenAI search crawler
+User-agent: OAI-SearchBot
+Allow: /
+
+# OpenAI training crawler
+User-agent: GPTBot
+Allow: /
+
+# Anthropic
+User-agent: ClaudeBot
+Allow: /
+
+# Perplexity
+User-agent: PerplexityBot
+Allow: /
+
+# Google Gemini / grounding
+User-agent: Google-Extended
+Allow: /
+
 User-agent: *
 Allow: /
 
 Sitemap: https://aptos.dev/sitemap-index.xml
 
 # LLMs.txt - Machine-readable documentation for AI tools
 # https://aptos.dev/llms.txt
+# https://aptos.dev/llms-small.txt
 # https://aptos.dev/llms-full.txt
 
 # Algolia-Crawler-Verif: F9CC1F2E397396BF
diff --git a/scripts/fix-i18n-links/README.md b/scripts/fix-i18n-links/README.md
@@ -4,7 +4,7 @@ A high-performance Rust tool for automatically fixing localized documentation li
 
 ## Problem
 
-Localized documentation (Spanish, Chinese, etc.) often contains internal links that lack proper locale prefixes. For example, a link to `/guide/setup` in Spanish docs should be `/es/guide/setup`.
+Localized documentation (Chinese, etc.) often contains internal links that lack proper locale prefixes. For example, a link to `/guide/setup` in Chinese docs should be `/zh/guide/setup`.
 
 ## Solution
 
@@ -41,7 +41,7 @@ pnpm fix-i18n-links
 
 The tool will:
 
-1. Auto-discover locale directories (e.g., `es/`, `zh/`)
+1. Auto-discover locale directories (e.g., `zh/`)
 2. Process all `.mdx` files in each locale
 3. Fix internal links by adding locale prefixes
 4. Report the number of files and links fixed

diff --git a/scripts/fix-i18n-links/src/main.rs b/scripts/fix-i18n-links/src/main.rs
@@ -58,7 +58,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     }
 
     if locales.is_empty() {
-        println!("{}", "ℹ️  No locale directories found (looking for 2-letter codes like es, zh)".yellow());
+        println!("{}", "ℹ️  No locale directories found (looking for 2-letter locale folders like zh)".yellow());
         return Ok(());
     }
 

diff --git a/src/components/SearchFallback.astro b/src/components/SearchFallback.astro
@@ -19,7 +19,6 @@
       fr: ["en"], // French falls back to English
       zh: ["en"], // Chinese falls back to English
       ja: ["en"], // Japanese falls back to English
-      es: ["en"], // Spanish falls back to English
     };
 
     function enhanceSearchWithFallbacks() {

diff --git a/src/components/SpanishBetaBanner.astro b/src/components/SpanishBetaBanner.astro
diff --git a/src/content/docs/build/ai.mdx b/src/content/docs/build/ai.mdx
@@ -51,4 +51,8 @@ can ingest to understand the full Aptos documentation. We publish three feeds to
 | **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | Condensed docs for smaller context windows                                |
 | **llms-full.txt**  | [`/llms-full.txt`](/llms-full.txt)   | Full documentation — all pages concatenated                               |
 
+Some clients resolve `/.well-known/llms.txt`; production serves the same index via a redirect to [`/llms.txt`](/llms.txt) ([`https://aptos.dev/.well-known/llms.txt`](https://aptos.dev/.well-known/llms.txt)).
+
+The [`llms.txt`](/llms.txt) router also surfaces machine-readable **API** links—[`/aptos-spec.json`](/aptos-spec.json) (OpenAPI 3 JSON for the node REST API) and [`/rest-api`](/rest-api) (HTML reference)—plus **MCP**, Agent Skills, Explorer, GitHub, standards, and Indexer GraphQL `.md` links in one place.
+
 <LinkCard href="/llms-txt" title="How to use LLMs.txt with AI tools" description="Instructions for Cursor, GitHub Copilot, Claude.ai, ChatGPT, Windsurf, and more" />
diff --git a/src/content/docs/llms-txt.mdx b/src/content/docs/llms-txt.mdx
@@ -12,20 +12,27 @@ We support [LLMs.txt](https://llmstxt.org/) files for making the Aptos documenta
 
 We provide the following LLMs.txt routes to help AI tools access our documentation:
 
-- [llms.txt](/llms.txt) - Contains a structured overview of Aptos LLMs.txt files
-- [llms-small.txt](/llms-small.txt) - Provides a condensed version of the documentation, optimized for smaller context windows
-- [llms-full.txt](/llms-full.txt) - Provides the full comprehensive documentation for all Aptos concepts
+- [llms.txt](/llms.txt) - A compact routing file that points AI tools to the most useful Aptos docs and machine-readable exports
+- [llms-small.txt](/llms-small.txt) - A curated low-token subset of the most useful Aptos documentation for IDE assistants and smaller context windows
+- [llms-full.txt](/llms-full.txt) - The full rendered Aptos documentation corpus for large-context ingestion
+
+**Well-known URL:** Some tools look for [`https://aptos.dev/.well-known/llms.txt`](https://aptos.dev/.well-known/llms.txt). That URL permanently redirects to [`/llms.txt`](/llms.txt) (same content).
+
+The [`llms.txt`](/llms.txt) index also lists **structured API assets** that are not prose docs—for example the [Aptos Fullnode OpenAPI spec](/aptos-spec.json) (JSON) and the [REST API reference](/rest-api) (HTML) generated from that spec.
+
+It also surfaces **agent tooling** (Aptos MCP, Agent Skills, Explorer, GitHub org) and key **Markdown** deep links (AI hub, standards, Indexer GraphQL reference) so models can fetch the right surface without guessing URLs.
 
 ## Per-Page Markdown Access
 
-Every documentation page is also available as raw Markdown by appending `.md` to the URL:
+Every documentation page is also available as rendered Markdown by appending `.md` to the URL:
 
-| Page URL                                           | Markdown URL                                          |
-| -------------------------------------------------- | ----------------------------------------------------- |
-| `https://aptos.dev/build/guides/first-transaction` | `https://aptos.dev/build/guides/first-transaction.md` |
-| `https://aptos.dev/build/sdks/ts-sdk`              | `https://aptos.dev/build/sdks/ts-sdk.md`              |
+| Page URL                                              | Markdown URL                                             |
+| ----------------------------------------------------- | -------------------------------------------------------- |
+| `https://aptos.dev/build/guides/first-transaction`    | `https://aptos.dev/build/guides/first-transaction.md`    |
+| `https://aptos.dev/build/sdks/ts-sdk`                 | `https://aptos.dev/build/sdks/ts-sdk.md`                 |
+| `https://aptos.dev/zh/build/guides/first-transaction` | `https://aptos.dev/zh/build/guides/first-transaction.md` |
 
-This is useful for AI tools that need to fetch individual pages with minimal tokens, rather than ingesting the full documentation. The [llms.txt](/llms.txt) index lists all pages with their `.md` URLs and descriptions so your AI tool can pick exactly which pages to read.
+This is useful for AI tools that need to fetch individual pages with minimal tokens, rather than ingesting the full documentation. The [llms.txt](/llms.txt) file acts as a compact router, while [llms-small.txt](/llms-small.txt) and [llms-full.txt](/llms-full.txt) provide curated and comprehensive corpus exports.
 
 ## Usage with AI Tools