#!/usr/bin/env python3

"""

Script to generate LLMs.txt source files.

Generates:

- llms.txt (English, curated index)

- llms-en.txt (source file for Lingo translations)

Also aligns startup guide discovery in existing locale and full-text indexes.

"""

import os

import re

import json

from pathlib import Path

# Configuration

REPO_ROOT = os.path.dirname(os.path.abspath(__file__))

OUTPUT_DIR = os.path.join(REPO_ROOT, 'apps', 'web', 'public')

STARTUP_GUIDE_URL = "https://solana.com/request-for-startups.md"

STARTUP_GUIDE_DESCRIPTION = "Explore video-based startup requests with speaker briefs and Solana tooling paths"

# AI agent resources section (English only, static URLs)

AI_AGENT_RESOURCES = [

("SKILL.md", "SKILL.md", "Comprehensive guide for AI agents to understand and build on Solana"),

("Full Documentation", "llms-full.txt", "Complete inline documentation with code examples and API reference"),

("Coding with Agents", "docs/intro/coding-with-agents", "Use Solana MCP and Agent Skills in AI-assisted development workflows"),

("Request for Startups", "request-for-startups.md", STARTUP_GUIDE_DESCRIPTION),

]

# Curated sections for the English source file

CURATED_SECTIONS = {

"Core Concepts": [

("Accounts", "docs/core/accounts", "How Solana stores data in accounts"),

("Transactions", "docs/core/transactions", "The fundamental building blocks for interacting with Solana"),

("Signing in Production", "docs/core/transactions/signing-in-production", "Where signing keys live in production and how to choose a backend"),

("Programs", "docs/core/programs", "Smart contracts on Solana"),

("Instructions", "docs/core/instructions", "Instruction structure and introspection"),

("Program Derived Addresses", "docs/core/pda", "Deterministic addresses for program-controlled accounts"),

("Cross Program Invocation", "docs/core/cpi", "How programs invoke other programs"),

("Fees on Solana", "docs/core/fees", "Transaction costs and priority fees"),

("Constants Reference", "docs/core/constants-reference", "Reference for Solana runtime constants"),

],

"Getting Started": [

("Introduction", "docs/intro", "Overview of Solana development"),

("Quick Start", "docs/intro/quick-start", "Build your first Solana program"),

("Installation", "docs/intro/installation", "Set up your local development environment"),

],

"Tokens": [

("Assets on Solana", "docs/tokens", "Token programs, accounts, and extensions on Solana"),

("Token Quickstart", "docs/tokens/quickstart", "Create a token with the Solana CLI"),

("Token Basics", "docs/tokens/basics", "SPL Token fundamentals"),

("Create Mint", "docs/tokens/basics/create-mint", "Create new token mints"),

("How to Verify a Token", "docs/tokens/how-to-verify-a-token", "Verify a token and display it in Solana Explorer"),

("Token Extensions", "docs/tokens/extensions", "Token-2022 program features"),

("Transfer Hook Integration", "docs/tokens/extensions/transfer-hook-integration", "Integrate Transfer Hook tokens in wallets, custodians, and dapps"),

("Advanced Token Instructions", "docs/tokens/advanced", "Advanced instructions for Solana token accounts"),

("Metaplex Metadata", "docs/tokens/metaplex", "Add and read metadata for Solana tokens"),

],

"Tokenization": [

("Asset Issuance & Tokenization", "docs/tokenization", "Issue and operate tokenized assets on Solana"),

("Tokenization Quickstart", "docs/tokenization/quickstart", "Launch a compliance-ready Token-2022 mint"),

("Token ACL", "docs/tokenization/token-acl", "Build permissioned tokens with allow and block lists"),

("Delivery vs Payment using delegation", "docs/tokenization/dvp", "Settle tokenized assets and payments atomically through delegated authority"),

("NAV Strikes", "docs/tokenization/nav-strikes", "Implement subscriptions and redemptions for tokenized funds"),

],

"Frontend": [

("@solana/client", "docs/frontend/client", "Headless client runtime for Solana frontends"),

("@solana/react-hooks", "docs/frontend/react-hooks", "React hooks and provider for Solana apps"),

("Next.js + Solana React Hooks", "docs/frontend/nextjs-solana", "Set up wallet integration in Next.js"),

("@solana/web3-compat", "docs/frontend/web3-compat", "Compatibility layer for legacy web3.js apps"),

],

"Client SDKs": [

("JavaScript/TypeScript SDK", "docs/clients/official/javascript", "Official TypeScript SDK for Solana"),

("Rust SDK", "docs/clients/official/rust", "Official Rust crates for Solana"),

("Python SDK", "docs/clients/community/python", "Community-maintained Python client"),

("Java SDK", "docs/clients/community/java", "Community-maintained Java client"),

("Go SDK", "docs/clients/community/go", "Community-maintained Go client"),

("Solana Gaming SDKs", "docs/clients/community/game-sdks", "Community SDKs for Solana game development"),

],

"References": [

("RPC Endpoints", "docs/references/clusters", "Network clusters, public RPC endpoints, and rate limits"),

("Staking", "docs/references/staking", "Staking concepts and stake account details"),

("Terminology", "docs/references/terminology", "Glossary of Solana terms and definitions"),

],

"RPC API": [

("JSON Reference", "docs/rpc/json-structures", "Shared response structures for Solana RPC"),

("HTTP Methods", "docs/rpc/http", "JSON-RPC API reference"),

("WebSocket Methods", "docs/rpc/websocket", "Real-time subscriptions"),

("Removed RPC Methods", "docs/rpc/deprecated", "Migration reference for removed RPC methods"),

],

"Finance": [

("Finance on Solana", "docs/finance", "Build tokenized assets, payments, and onchain markets"),

("Privacy", "docs/finance/privacy", "Compare privacy tools for financial applications on Solana"),

],

"Payments": [

("Payments Overview", "docs/payments", "Build payment systems with instant settlement"),

("Payments Quickstart", "docs/payments/quickstart", "Build a first stablecoin payment flow"),

("How Payments Work", "docs/payments/how-payments-work", "Core concepts for Solana payments"),

("Interacting with Solana", "docs/payments/interacting-with-solana", "Send and confirm payments through Solana"),

("Send Payments", "docs/payments/send-payments", "Send stablecoin payments with memos and batching"),

("Accept Payments", "docs/payments/accept-payments", "Integrate checkout and payment acceptance"),

("Developer Tools", "docs/payments/developer-tools", "Libraries and services for building payment flows"),

("Production Readiness", "docs/payments/production-readiness", "Prepare payment systems for mainnet"),

("Agentic Payments", "docs/payments/agentic-payments", "Enable autonomous payments for AI agents with x402"),

("Spend Permissions", "docs/payments/advanced-payments/spend-permissions", "Delegate token spending with a capped allowance"),

("Deferred Execution", "docs/payments/advanced-payments/deferred-execution", "Sign transactions for later submission with durable nonces"),

],

"DeFi": [

("Markets & Trading", "docs/defi", "Build trading systems and onchain financial applications"),

("Exchange Integration", "docs/defi/exchange", "Add Solana deposits and withdrawals to an exchange"),

("MEV Protection", "docs/defi/mev-protection", "Protect transactions from sandwich attacks with Jito DontFront"),

("Stake-weighted QoS", "docs/defi/stake-weighted-qos", "Prioritize transactions through staked validators"),

("Delivery vs Payment (DvP) program", "docs/defi/dvp-program", "Escrowed atomic settlement of an asset leg against a cash leg"),

("Create a Trade", "docs/defi/dvp-program/create-a-trade", "Set up the DvP clients and record a trade's terms"),

("Fund the Legs", "docs/defi/dvp-program/fund-the-legs", "Verify the stored terms and fund a leg with a plain transfer"),

("Settle the Trade", "docs/defi/dvp-program/settle-the-trade", "Settle a funded trade as the settlement authority"),

("Unwind a Trade", "docs/defi/dvp-program/unwind-a-trade", "Reclaim, cancel, reject, and recover late deposits"),

],

"Tools": [

("Tools", "docs/tools", "Developer tool documentation"),

("Install Dependencies", "docs/intro/installation/dependencies", "Install Rust, the Solana CLI, and Anchor"),

("Solana CLI Basics", "docs/intro/installation/solana-cli-basics", "Common commands for the Solana CLI"),

("Anchor CLI Basics", "docs/intro/installation/anchor-cli-basics", "Common commands for the Anchor CLI"),

("Surfpool CLI Basics", "docs/intro/installation/surfpool-cli-basics", "Common commands for the Surfpool CLI"),

("Kora", "docs/tools/kora", "Solana signing infrastructure"),

("Keychain", "docs/tools/keychain", "Unified Solana signing across key management backends"),

("Choosing a Signing Backend", "docs/tools/keychain/choosing-a-backend", "Compare custody models and pick a Keychain backend"),

("Solana Pay", "docs/tools/solana-pay", "Standard protocol for decentralized payments on Solana"),

("Attestations", "docs/tools/attestations", "Verifiable claims and credentials on Solana"),

("Private Channels", "docs/tools/private-channels", "Enterprise layer for internet capital markets"),

("Rewards Program", "docs/tools/rewards", "Token distributions with vesting, merkle claims, and revocation"),

("LiteSVM", "docs/tools/litesvm", "Test Solana programs with an in-process virtual machine"),

("Surfpool", "docs/tools/surfpool", "Simulate Solana programs locally with mainnet accounts"),

("Surfpool Kit Plugin", "docs/tools/surfpool/sdk/kit-plugin", "Run a local Surfnet behind a Solana Kit client"),

("Actions and Blinks", "docs/tools/actions", "Build Solana Actions APIs and shareable blinks"),

("AI Tools and Agents", "docs/tools/ai", "Use AI tools and agents when building on Solana"),

],

}

# Additional English-only sections

ENGLISH_EXTRAS = {

"Documentation": [

("Documentation Tags", "docs/tags", "Browse documentation pages grouped by topic tags"),

],

"Video Tutorials": [

("Video Tutorials", "docs/video-guides", "Courses and hands-on Solana projects"),

("Solana Crash Course", "docs/video-guides/solana-crash-course", "Build from environment setup through program deployment"),

("2026 Developer Bootcamp", "docs/video-guides/2026-developer-bootcamp", "Build Solana projects in a long-form course"),

],

"Learn": [

("What is Solana", "learn/what-is-solana", "Introduction to Solana for beginners"),

("A Poker Player's Guide to Crypto Trading on Solana", "poker-players-guide-to-crypto", "An introduction to crypto trading for poker players, built around skills you already have."),

("What is a Wallet", "learn/what-is-a-wallet", "Understanding crypto wallets"),

("Getting Started", "learn/getting-started", "First steps with Solana"),

("Introduction to DeFi", "learn/introduction-to-defi-on-solana", "Decentralized finance on Solana"),

("Introduction to Tokens", "learn/introduction-to-solana-tokens", "Understanding SPL tokens"),

("Transaction Fees", "learn/understanding-solana-transaction-fees", "How transaction fees work on Solana"),

("Sending and Receiving SOL", "learn/sending-and-receiving-sol", "Transfer SOL using a wallet"),

("What is Staking", "learn/what-is-staking", "Earn rewards by helping secure the network"),

("What are NFTs", "learn/what-are-nfts", "Unique digital assets on Solana"),

("Solana Applications", "learn/exploring-solana-applications", "Discover applications built on Solana"),

("Staying Safe", "learn/staying-safe-on-solana", "Security practices for using Solana"),

],

"Cookbook": [

("Send SOL", "developers/cookbook/transactions/send-sol", "Transfer SOL between accounts"),

("Create Account", "developers/cookbook/accounts/create-account", "Create accounts on Solana"),

("Get Balance", "developers/cookbook/accounts/get-account-balance", "Retrieve SOL balance"),

("Add Priority Fees", "developers/cookbook/transactions/add-priority-fees", "Increase transaction priority"),

("Create Keypair", "developers/cookbook/wallets/create-keypair", "Generate new keypairs"),

],

"Guides": [

("AI Tools on Solana", "developers/guides/getstarted/intro-to-ai", "Overview of AI tools and workflows on Solana"),

("Introduction to x402", "developers/guides/getstarted/intro-to-x402", "Build a simple HTTP 402 payment flow"),

("Build an x402 Facilitator", "developers/guides/getstarted/build-a-x402-facilitator", "End-to-end x402 facilitator demo"),

("Actions and Blinks", "developers/guides/advanced/actions", "Build Solana Actions APIs and shareable blinks"),

("Game Development Quickstart", "developers/guides/games/getting-started-with-game-development", "Get started building games on Solana"),

("DePIN Getting Started", "developers/guides/depin/getting-started", "Build decentralized physical infrastructure on Solana"),

("Durable Nonces", "developers/guides/advanced/introduction-to-durable-nonces", "Use durable nonces for offline signing"),

("Lookup Tables", "developers/guides/advanced/lookup-tables", "Reduce transaction size with address lookup tables"),

("Transfer Hook", "developers/guides/token-extensions/transfer-hook", "Implement custom logic on token transfers"),

],

"Program Development": [

("Developing Programs", "docs/programs", "Build onchain programs"),

("Anchor Framework", "docs/programs/anchor", "High-level framework for Solana programs"),

("Testing Programs", "docs/programs/testing", "Test programs with bankrun and other tools"),

("Rust Programs", "docs/programs/rust", "Build Solana programs in Rust"),

("Deploying Programs", "docs/programs/deploying", "Deploy Solana programs to a cluster"),

("IDLs", "docs/programs/idls", "Define interfaces for Solana programs"),

("Generating Clients", "docs/programs/codama/clients", "Generate TypeScript and Rust clients from a program IDL"),

("Verifying Programs", "docs/programs/verified-builds", "Verify deployed Solana program builds"),

("Program Examples", "docs/programs/examples", "Examples for building Solana programs"),

("Program Limitations", "docs/programs/limitations", "Runtime and resource limits for Solana programs"),

],

"EVM to SVM": [

("Solana for EVM Developers", "developers/evm-to-svm", "Learn about the key differences in building between Solana and Ethereum"),

("Complete Guide", "developers/migrate-to-solana/complete-guide", "A complete guide to Solana development for Ethereum developers"),

("Accounts", "developers/evm-to-svm/accounts", "See how accounts differ between Ethereum and Solana"),

("Client Differences", "developers/evm-to-svm/client-differences", "See the difference between clients and types in SVM vs EVM"),

("Consensus", "developers/evm-to-svm/consensus", "Learn how consensus works on Solana compared to Ethereum"),

("EIP-2612", "developers/evm-to-svm/eip2612", "Learn how to build EIP-2612 on Solana"),

("ERC20", "developers/evm-to-svm/erc20", "Learn how to build ERC20 on Solana using the Token Program"),

("ERC3643", "developers/evm-to-svm/erc3643", "Learn how to build ERC3643 on Solana"),

("ERC4337", "developers/evm-to-svm/erc4337", "Learn how to build ERC4337 on Solana"),

("ERC4626", "developers/evm-to-svm/erc4626", "Learn how to build ERC4626 on Solana"),

("ERC721", "developers/evm-to-svm/erc721", "Learn how to build ERC721 on Solana using Metaplex"),

("Smart Contracts", "developers/evm-to-svm/smart-contracts", "Explore programs and how they work on Solana"),

],

"Bootcamp": [

("Bootcamp", "developers/bootcamp", "Structured Solana developer learning path"),

("Solana Crashcourse", "developers/bootcamp/solana-crashcourse", "Fast path to building and deploying on Solana"),

("Foundations", "developers/bootcamp/foundations", "Core blockchain and Solana development lessons"),

("Program Patterns", "developers/bootcamp/program-patterns", "Common onchain program patterns"),

("Fullstack Applications", "developers/bootcamp/fullstack-apps", "Build fullstack applications on Solana"),

("Shipping & Production", "developers/bootcamp/shipping-production", "Prepare Solana applications for production"),

("DePIN", "developers/bootcamp/depin", "Build decentralized physical infrastructure applications"),

],

"Accelerate": [

("Solana Accelerate", "accelerate", "Solana's global community event series in 2026"),

("Accelerate APAC", "accelerate/hong-kong", "Solana Accelerate APAC in Hong Kong"),

("APAC Agenda", "accelerate/hong-kong/agenda", "Sessions and speakers for Accelerate APAC"),

("Accelerate Miami", "accelerate/miami", "Solana Accelerate USA in Miami"),

("Miami Agenda", "accelerate/miami/agenda", "Sessions and speakers for Accelerate Miami"),

],

}

def normalize_llms_urls(content: str) -> str:

content = re.sub(

r"https://solana\.com/docs/en(?=/|$)",

"https://solana.com/docs",

content,

)

content = re.sub(

r"https://solana\.com/docs/([a-z]{2})(?=/)",

r"https://solana.com/\1/docs",

content,

)

content = re.sub(

r"https://solana\.com/cookbook(?=/|$)",

"https://solana.com/developers/cookbook",

content,

)

return content

def generate_startup_requests() -> str:

"""Read the same request titles, anchors, and theses used by the page."""

catalog_path = Path(REPO_ROOT) / "packages/i18n/messages/web/en/common.json"

catalog = json.loads(catalog_path.read_text(encoding="utf-8"))

requests = catalog["request-for-startups"]["requests"]["items"]

lines = [

"## Request for Startups",

"",

f"Use the [startup guide]({STARTUP_GUIDE_URL}) to choose a request and plan a first build. Each brief follows one video from the playlist and includes the speaker, opportunity, starting points, and tooling path.",

"",

]

for slug, request in requests.items():

lines.append(

f"- [{request['title']}]({STARTUP_GUIDE_URL}#{slug}): {request['thesis']}"

)

return "\n".join(lines)

def align_existing_agent_indexes(startup_requests: str):

"""Add canonical guide discovery without rewriting translated or full docs."""

for path in sorted(Path(OUTPUT_DIR).glob("llms-*.txt")):

if path.name == "llms-en.txt":

continue

content = path.read_text(encoding="utf-8")

if path.name == "llms-full.txt":

heading = "## Request for Startups\n"

if heading in content:

start = content.index(heading)

end = content.find("\n## ", start + len(heading))

end = end if end >= 0 else len(content)

content = content[:start] + startup_requests + "\n\n---\n" + content[end:]

else:

marker = "## Core Concepts\n"

content = content.replace(marker, startup_requests + "\n\n---\n\n" + marker, 1)

else:

# The brief is English; preserve the locale's translated documentation.

link = f"- [Request for Startups (English)]({STARTUP_GUIDE_URL}): {STARTUP_GUIDE_DESCRIPTION}"

if STARTUP_GUIDE_URL in content:

content = re.sub(

r"^- \[[^\n]+\]\(https://solana\.com/request-for-startups\.md\):[^\n]*$",

lambda _: link,

content,

flags=re.MULTILINE,

)

else:

first_section = content.find("\n## ")

next_section = content.find("\n## ", first_section + 1)

if first_section < 0 or next_section < 0:

raise ValueError(f"Cannot locate agent resource section in {path}")

content = content[:next_section].rstrip() + "\n" + link + "\n\n" + content[next_section + 1:]

path.write_text(content, encoding="utf-8")

print(f"Aligned: {path}")

def generate_llms_txt() -> str:

"""Generate llms.txt content for the English source file."""

base_url = "https://solana.com"

lines = [

"# Solana",

"",

"> Solana is the high-performance blockchain designed for mass adoption, capable of processing thousands of transactions per second with sub-second finality.",

"",

"This documentation provides comprehensive guides, references, and tutorials for developers building on Solana.",

"",

"## AI Agent Resources",

"",

]

# Add AI agent resources

for title, path, description in AI_AGENT_RESOURCES:

url = f"{base_url}/{path}"

lines.append(f"- [{title}]({url}): {description}")

lines.append("")

lines.extend([generate_startup_requests(), ""])

# Add curated sections

for section_name, links in CURATED_SECTIONS.items():

lines.append(f"## {section_name}")

lines.append("")

for title, path, description in links:

url = f"{base_url}/{path}"

lines.append(f"- [{title}]({url}): {description}")

lines.append("")

# Add English-only extras

for section_name, links in ENGLISH_EXTRAS.items():

lines.append(f"## {section_name}")

lines.append("")

for title, path, description in links:

url = f"{base_url}/{path}"

lines.append(f"- [{title}]({url}): {description}")

lines.append("")

# Add optional resources section

lines.append("## Optional")

lines.append("")

lines.append("- [Solana StackExchange](https://solana.stackexchange.com): Community Q&A")

lines.append("- [Validator Setup](https://docs.anza.xyz/operations/setup-a-validator): Run a validator node")

lines.append("")

return "\n".join(lines)

def write_output(filename: str, content: str) -> str:

output_path = os.path.join(OUTPUT_DIR, filename)

with open(output_path, "w", encoding="utf-8") as f:

f.write(content)

return output_path

def main():

os.makedirs(OUTPUT_DIR, exist_ok=True)

content = normalize_llms_urls(generate_llms_txt())

for filename in ("llms-en.txt", "llms.txt"):

output_path = write_output(filename, content)

print(f"Generated: {output_path}")

align_existing_agent_indexes(generate_startup_requests())

print("\nTranslations are handled by Lingo via .github/workflows/i18n.yml")

if __name__ == "__main__":

main()