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.

Concern	Source of truth	Spec / reference
Global `Link` response header	`vercel.json` → `headers[source="/(.*)"]`	RFC 8288
In-page discovery `<link rel="…">`	`src/starlight-overrides/Head.astro`	RFC 8288
API catalog	`public/.well-known/api-catalog`	RFC 9727
MCP Server Card	`public/.well-known/mcp/server-card.json`	SEP-2127
Agent Skills index	`public/.well-known/agent-skills/index.json`	Agent Skills Discovery RFC v0.2.0
Agent Skills regeneration	`scripts/generate-agent-skills-index.mjs`	Pins `sha256:` digests from `aptos-labs/aptos-agent-skills@main`
Content Signals	`public/robots.txt` → `Content-Signal:` line	contentsignals.org
OAuth Protected Resource Metadata	`public/.well-known/oauth-protected-resource` (only the Aptos Testnet Faucet is OAuth-protected)	RFC 9728
OIDC / OAuth 2.0 discovery	`public/.well-known/openid-configuration`, `public/.well-known/oauth-authorization-server`	OpenID Connect Discovery 1.0, RFC 8414
Markdown content negotiation	`src/middlewares/markdown-negotiation.ts` + `src/vercel-middleware.ts`	Rewrites `Accept: text/markdown` requests to the `.md` export.
Middleware matcher + bundle	`scripts/generate-middleware-matcher.js`, `scripts/generate-middleware.js`, committed `middleware.js`	Matcher covers the locales + route prefixes middleware should run on. `generate-middleware.js` also copies the bundled middleware to the repo root so `scripts/generate-middleware-function.js` ships it — never hand-edit `middleware.js`.
MCP card regeneration	Hand-maintained `public/.well-known/mcp/server-card.json` pinned to a real `@aptos-labs/aptos-mcp` version	Bump the `version` field and both `packages[0].version` + `packages[0].transport.args` whenever the npm package is released; never use `latest`.
WebMCP tools	`src/scripts/webmcp-register.ts` (+ `src/types/webmcp.d.ts`, `src/components/WebMcpRegistration.astro`)	WebMCP draft
User-facing explainer	`src/content/docs/build/ai.mdx` and `src/content/docs/zh/build/ai.mdx`	Keep the endpoint table and example `curl` in sync.

Keep-fresh checklist when editing any of the above:

Update the endpoint or config. Changes to the Link header, MCP card, api-catalog, or Agent Skills index 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).
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.
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.
Run the guardrail tests. pnpm test tests/agent-discovery.test.ts tests/markdown-negotiation.test.ts asserts the Link header, well-known payload shapes, Content Signals, Content-Type routing, and the markdown-negotiation routing decisions still line up. Both suites run as part of the default pnpm test.
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).
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.

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

Command	Description
`pnpm dev`	Start the development server
`pnpm build`	Build the site for production
`pnpm lint`	Check for linting issues
`pnpm format`	Fix formatting issues
`pnpm check`	Run Astro type checking
`pnpm format:content`	Format MDX content files

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:

Make the change in the English version first
Create or update the corresponding Chinese translation in zh/
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:

Define the term clearly - Provide a concise, accurate definition
Provide an example - Include practical examples or use cases
Add context - Link to related documentation where appropriate
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

Create the MDX file in the appropriate directory
Add frontmatter with title and description
Create Chinese translation in zh/ subdirectory
Update sidebar configuration if needed (astro.sidebar.ts)
Run pnpm lint and pnpm format

Updating the Glossary

Add the term to src/content/docs/network/glossary.mdx
Add Chinese translation to src/content/docs/zh/network/glossary.mdx
Ensure alphabetical ordering within each section
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 (Algolia DocSearch) is disabled in dev mode; this is expected.

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CLAUDE.md - AI Agent Guidelines for Aptos Documentation

Project Overview

Machine-readable documentation for agents

Agent discovery & readiness (keep fresh!)

Development Setup

Prerequisites

Quick Start

Essential Commands

Project Structure

Critical Guidelines

1. Linting and Formatting

2. Translation Requirements

3. Commit Message Requirements

4. Grammar and Style

5. Glossary Requirements

6. MDX File Structure

7. Internal Links

Content Guidelines

Writing Style

Code Blocks

Common Tasks

Adding a New Documentation Page

Updating the Glossary

Resources

Cursor Cloud specific instructions

Environment setup

Running the dev server

Linting and testing

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md - AI Agent Guidelines for Aptos Documentation

Project Overview

Machine-readable documentation for agents

Agent discovery & readiness (keep fresh!)

Development Setup

Prerequisites

Quick Start

Essential Commands

Project Structure

Critical Guidelines

1. Linting and Formatting

2. Translation Requirements

3. Commit Message Requirements

4. Grammar and Style

5. Glossary Requirements

6. MDX File Structure

7. Internal Links

Content Guidelines

Writing Style

Code Blocks

Common Tasks

Adding a New Documentation Page

Updating the Glossary

Resources

Cursor Cloud specific instructions

Environment setup

Running the dev server

Linting and testing