CLAUDE.md - AI Agent Guidelines for Aptos Documentation

This document provides essential guidelines for AI agents working on the Aptos Developer Documentation repository.

Project Overview

This repository contains the official Aptos Developer Documentation, built using Astro and Starlight. Published languages include English and Chinese (zh). Agent workflows here do not include creating or updating Spanish (es) documentation.

Machine-readable documentation for agents

Production docs are indexed for LLMs and coding agents at https://aptos.dev/llms.txt (same content as 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 page.

Agent discovery & readiness (keep fresh!)

The site advertises a full set of agent-discovery endpoints. Treat these as a single surface — if you touch one, audit the rest, update the matching docs, regenerate any required artifacts (pnpm build:middleware-matcher for matcher changes; pnpm build:middleware when the middleware bundle needs to ship), and then re-run pnpm test tests/agent-discovery.test.ts tests/markdown-negotiation.test.ts. The guardrail tests regenerate the matcher on demand, so a clean checkout still passes.

Keep-fresh checklist when editing any of the above:

1. Update the endpoint or config. Changes to the Link header, MCP card, api-catalog, Agent Skills index, ARD catalog, or /sitemap.xml alias must go hand in hand — adding a new well-known endpoint means adding it to vercel.json (header + Content-Type) and the Head override and the build/ai.mdx tables (English + Chinese).
2. Regenerate skill digests. After bumping a skill in aptos-labs/aptos-agent-skills, run node scripts/generate-agent-skills-index.mjs so sha256: digests match upstream. Don't hand-edit the JSON.
3. Rebuild the middleware bundle. After any change to src/vercel-middleware.ts, the middleware order, the matcher, or any file under src/middlewares/*, run pnpm build:middleware. It regenerates both .vercel/output/middleware/middleware.js and the repo-root middleware.js (Prettier-formatted) that Vercel ships, so the committed bundle stays in sync with the TypeScript source.
4. Run the guardrail tests. pnpm test tests/agent-discovery.test.ts tests/markdown-negotiation.test.ts tests/sitemap-xml-alias.test.ts asserts the Link header, well-known payload shapes, Content Signals, /sitemap.xml alias wiring, Content-Type routing, and the markdown-negotiation routing decisions still line up. These suites run as part of the default pnpm test.
5. Update translations. Anything added to src/content/docs/build/ai.mdx must appear in src/content/docs/zh/build/ai.mdx (Spanish is out of scope).
6. Verify in production. Once deployed, re-scan with curl -sI https://aptos.dev/ | rg '^link:' and an "Is It Agent Ready?" scan. If a signal regressed, note the fix in the PR description. DNS-AID (_index._agents.aptos.dev) is published in Google Cloud DNS, not this repo — the HTTPS record already exists; a scanner fail there means the zone still needs a parent DS so DNSSEC validates (AD=1). The ARD catalog TXT (_catalog._agents.aptos.dev) is also DNS-only.

WebMCP specifics:

• The tool definitions live in src/scripts/webmcp-register.ts and are type-checked via src/types/webmcp.d.ts. Use those types when adding new tools — don't reach for is:inline scripts or any.
• The tool names (aptos-docs.search, aptos-docs.open-doc, aptos-docs.fetch-doc-markdown, aptos-docs.list-llms-feeds) are documented in build/ai.mdx; keep that list in sync when adding/removing tools.
• Markdown negotiation relies on the per-page .md exports from src/pages/[...slug].md.ts. Route changes that break those exports will also break the fetch-doc-markdown WebMCP tool.

Development Setup

Prerequisites

• Node.js: Version 22.23.0 (use mise or another .tool-versions-compatible manager)
• pnpm: Version 11.x (npm install -g pnpm)

Quick Start

pnpm install        # Install dependencies
cp .env.example .env  # Set up environment variables
pnpm dev            # Start development server (http://localhost:4321)

Essential Commands

Project Structure

src/
├── content/
│   ├── docs/           # Main English documentation
│   │   └── zh/         # Chinese translations
│   ├── i18n/           # UI translations
│   └── nav/            # Sidebar translations
├── components/         # Reusable components
├── config/             # Configuration helpers
└── assets/             # Site assets

A legacy docs/es/ tree or URLs may still exist for redirects; do not add or maintain Spanish doc content under these agent guidelines.

Critical Guidelines

1. Linting and Formatting

IMPORTANT: All changes must pass linting and formatting checks before completion.

pnpm lint      # Run all linters (eslint + prettier)
pnpm format    # Fix formatting issues

Run these commands after making changes to ensure code quality.

2. Translation Requirements

Documentation changes that need localization must include the Chinese (zh) version. Do not add or update Spanish (es) translations as part of agent work.

• English docs: src/content/docs/
• Chinese docs: src/content/docs/zh/

When modifying documentation:

1. Make the change in the English version first
2. Create or update the corresponding Chinese translation in zh/
3. Ensure Chinese internal links use the /zh/... prefix (see Internal Links below)

3. Commit Message Requirements

Every commit should have a clear, descriptive message that explains the changes made.

Format:

<type>: <description>

<optional body with more details>

Types:

• docs: Documentation changes
• feat: New features
• fix: Bug fixes
• style: Formatting changes
• chore: Maintenance tasks

Example:

docs: add glossary entry for BlockSTM

Added definition and example for BlockSTM parallel execution engine.
Updated Chinese translation accordingly.

4. Grammar and Style

Grammar check every change before committing. Ensure:

• Clear, concise language
• Consistent terminology throughout the documentation
• Proper sentence structure and punctuation
• Technical accuracy in all explanations
• Active voice preferred over passive voice

5. Glossary Requirements

Ensure new terms are defined in the Glossary.

The glossary is located at:

• English: src/content/docs/network/glossary.mdx
• Chinese: src/content/docs/zh/network/glossary.mdx

When adding a new term to the glossary:

1. Define the term clearly - Provide a concise, accurate definition
2. Provide an example - Include practical examples or use cases
3. Add context - Link to related documentation where appropriate
4. Consider diagrams - Add diagrams for complex concepts when helpful

Glossary entry format:

### Term Name

- **Term Name** is [definition].
- [Additional context or explanation].

See [Related Page](/path/to/page) for more information.

6. MDX File Structure

Documentation files use MDX format with frontmatter:

---
title: "Page Title"
description: "Brief description of the page content"
sidebar:
  label: "Sidebar Label" # Optional
---

7. Internal Links

Use relative paths without the file extension:

• English: /network/blockchain/accounts
• Chinese: /zh/network/blockchain/accounts

Content Guidelines

Writing Style

• Use clear, simple language accessible to developers of all skill levels
• Define technical terms on first use or link to the glossary
• Include code examples where appropriate
• Structure content with clear headings and subheadings

Code Blocks

Use fenced code blocks with language identifiers:

module example::hello {
    public fun greet(): vector<u8> {
        b"Hello, Aptos!"
    }
}

Common Tasks

Adding a New Documentation Page

1. Create the MDX file in the appropriate directory
2. Add frontmatter with title and description
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 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

• LLM and SEO readiness (Cursor skill) — checklists for llms.txt, curated feeds, .md exports, and metadata/crawlers
• Astro Documentation
• Starlight Documentation
• MDX Documentation
• Aptos Developer Portal

Cursor Cloud specific instructions

This is a single-service Astro/Starlight documentation site. No databases, Docker, or external services are required for local development.

Environment setup

• The VM snapshot provides Node 24+ and pnpm 11.8.0. The update script runs pnpm install automatically, so Biome, TypeScript, and Vitest are ready without manual setup.
• Ensure .env exists (copy from .env.example if missing). Default values are sufficient for local dev; optional services (Firebase, Algolia, OG images) degrade gracefully when their env vars are empty.
• pnpm may warn about ignored build scripts for native packages (@swc/core, esbuild, sharp, etc.) — these warnings are safe to ignore as the packages ship pre-built binaries.
• The repo's .tool-versions pins nodejs 22.23.0; engines says >=22, but Node 24 is fully compatible and is what this environment uses.

Running the dev server

• pnpm dev starts the Astro dev server at http://localhost:4321.
• The predev script automatically builds middleware matcher and starts middleware watcher in the background.
• Search is disabled in dev mode; this is expected. Which provider a build ships (Algolia DocSearch or Starlight's Pagefind fallback) is decided in src/config/search.ts; run pnpm check:search to see the current decision.

Linting and testing

• pnpm lint runs Biome and Prettier in parallel (not ESLint, despite what some comments say).
• pnpm test runs Vitest tests.
• pnpm check runs Astro type checking.
• Git hooks: pre-commit runs nano-staged (Biome + Prettier on staged files), pre-push runs astro check --noSync.