Migration

CLAUDE.md

@@ -1,78 +1,121 @@
-# CLAUDE.md - Repository Assistant Guide
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Repository Overview
-This is the ar-io/docs repository, which manages the documentation for the ar.io Developer Platform. It references various services, SDKs and tools for building on and with ar.io. It also includes documentation for interacting with ArDrive - a flagship consumer dApp that stores data on Arweave.
+
+Documentation site for the ar.io Developer Platform, covering services, SDKs, and tools for building on ar.io and Arweave. Built with [Fumadocs](https://fumadocs.dev/) on Next.js. Live site: [docs.ar.io](https://docs.ar.io)
+
+## Key Commands
+
+```bash
+npm run dev              # Start dev server (Turbo, standalone mode, no trailing slashes)
+npm run build            # Production build (static export to out/, trailing slashes)
+npm run lint             # ESLint (src/ and content/, .ts/.tsx/.mdx)
+npx tsc --noEmit         # TypeScript type checking
+npm run check-links      # Validate internal/external links
+
+# Content generation
+npm run generate-api-docs      # Generate OpenAPI docs from ar-io-node + turbo services
+npm run generate-sdk-docs      # Generate SDK reference from external repo READMEs
+npm run generate-llm-text      # Generate public/llms-full.txt
+npm run generate-sdk-llm-texts # Generate per-SDK llm.txt files
+npm run generate-all-docs      # Run all generation scripts (except API docs)
+```
+
+Note: The `postinstall` script runs `fumadocs-mdx` to generate the `.source/` directory (content type definitions and index). This must run before the dev server or build will work. If `.source/` is missing, run `npm install` or `npx fumadocs-mdx`. The package manager is **yarn 1.22.22** (specified in `package.json`).
 
 ## Architecture
-This repository is built with [Fumadocs](https://fumadocs.dev/), a documentation framework. The general architecture is as follows:
 
-### UI Components
-All UI should use Fumadocs available UI components by default. This ensures consistency with the framework's design system and maintains a cohesive user experience throughout the documentation.
+### Build Modes
+- **Development** (`npm run dev`): Standalone Next.js server with Turbo, hot reload, no trailing slashes. Redirects from `redirects.mjs` work here.
+- **Production** (`npm run build`): Static export (`output: "export"`) to `out/`, trailing slashes enabled, unoptimized images. ESLint errors are ignored during production builds. Redirects from `redirects.mjs` do **not** work (static export limitation).
 
-All icons should use lucide-react for consistency across the documentation site.
+### Routing
+- `src/app/[[...slug]]/` - Single catch-all route handles all documentation pages
+- `src/app/[[...slug]]/page.tsx` - Renders MDX content, generates static params, handles metadata/OG tags
+- `src/app/api/search/route.ts` - Orama full-text search endpoint
+- 404s redirect to `/learn` as a fallback
 
-## Key Commands
-- **Linting**: `npm run lint` - Run ESLint to check code quality
-- **Type checking**: `npm run typecheck` - Run TypeScript type checking
-- **Development server**: `npm run dev` - Start the development server
-- **Build**: `npm run build` - Build the documentation site
-
-## Repository Structure
-- `/content/` - Main documentation content
-  - `/content/docs/` - Core documentation pages
-  - `/content/api/` - API documentation
-  - `/content/guides/` - User guides and tutorials
-- `/public/` - Static assets
-- `/src/` - Source code for documentation site
-- `/scripts/` - Build and utility scripts
-
-## Documentation Guidelines
-- Documentation is written in MDX format (Markdown with JSX)
-- Use semantic headings (H1 for page title, H2 for main sections, etc.)
-- Include code examples with proper syntax highlighting
-- Add metadata frontmatter to all documentation pages
-- Follow existing documentation patterns and structure
-
-### Documentation Philosophy
-These docs intend to model documentation sites of well-established platforms like Stripe, Coinbase, and ChatGPT - where users can natively find things logically, and patterns are consistent throughout. Key principles:
-- Logical information architecture
-- Consistent navigation patterns
-- Clear categorization of content
-- Predictable documentation structure
-- User-friendly search and discovery
-
-## Working with OpenAPI
-The repository supports OpenAPI documentation import (see recent commit 33af22f2e). When working with API documentation:
-- OpenAPI specs should be properly formatted YAML or JSON
-- Use the import scripts to convert OpenAPI to documentation format
-- Maintain consistency with existing API documentation structure
-
-## Git Workflow
-- Main branch: `main`
-- Create feature branches for new work
-- Use descriptive commit messages
-- Run linting and type checking before committing
-
-## Community Resources
-- **Discord**: https://discord.com/invite/HGG52EtTc2 - Join the ar.io community for updates and discussions
-
-## Important Notes
-- This is a documentation repository - focus on content clarity and accuracy
-- Always verify technical details match the actual ar.io implementation
-- Maintain consistent terminology throughout documentation
-- Test all code examples before including them in documentation
-
-## Recent Updates
-- **Access Data Documentation**: Restructured `/content/build/access/` pages with consistent patterns:
-  - Updated index.mdx to show three access methods (Find Data, Fetch Data, ArNS) with enhanced cards
-  - Renamed and reorganized find-data.mdx (GraphQL) and fetch-data.mdx (REST API) for clarity
-  - Enhanced ArNS documentation with practical SDK examples
-  - Used native Fumadocs cards with icons for consistency
-  - Replaced axios with fetch API in all examples
-  - Added proper call-to-action sections directing users to next steps
-- **Upload Data Documentation**: Enhanced `/content/build/upload/index.mdx` with native cards and clear Turbo recommendation
-- **Code Standards**: 
-  - Use `fetch` instead of `axios` for HTTP requests
-  - Use `ARIO.mainnet()` from '@ar.io/sdk' for ArNS operations
-  - Call `setRecord` on ANT instances, not ARIO instances
-  - ArNS undernames use underscores (e.g., `api_myapp.arweave.net`) not periods
+### Content Source Pipeline
+- `source.config.ts` - Fumadocs MDX configuration: registers remark plugins (Mermaid, math) and rehype plugins (KaTeX)
+- `src/lib/source.ts` - Content loader using `fumadocs-core`'s `loader()`, with:
+  - OpenAPI transformer for API reference pages
+  - Alphabetical sorting for `build/guides` folder (via `ALPHABETICALLY_SORTED_FOLDERS`)
+  - Icon resolution from `meta.json` - supports Lucide icon names, SVG/PNG paths, and the special `ThemeIcon` for dark/light variants
+- `.source/` (generated) - TypeScript types and content index produced by `fumadocs-mdx`
+- `src/mdx-components.tsx` - All MDX components registered here, including 18 Lucide icons available as JSX in MDX files
+- `src/lib/layout.shared.tsx` - Shared layout options (nav, theme, conditional links)
+
+### Content Organization
+- `content/` - All documentation in MDX format
+  - `content/learn/` - Conceptual documentation (ArNS, gateways, token, etc.)
+  - `content/build/` - Developer guides (access data, upload, run gateway)
+  - `content/sdks/` - SDK documentation (ar-io-sdk, turbo-sdk, ardrive-cli, wayfinder)
+  - `content/apis/` - API reference (ar-io-node, turbo services)
+- `content/meta.json` - Root navigation structure
+- Each folder uses `meta.json` to define page order and navigation
+- Parenthesized folders like `(introduction)` are route groups (removed from URL)
+
+### Path Aliases
+- `@/*` → `./src/*`
+- `@/.source` → `./.source/index.ts` (Fumadocs generated content)
+
+### Key Components
+- **Ask Arie** (`src/components/ask-arie/`) - AI chat widget with session persistence (sessionStorage), thread management, health checks against 3 backend APIs, and citation rendering
+- **Page Actions** (`src/components/page-actions.tsx`) - LLM copy button (fetches raw markdown from GitHub) and "Open in AI" dropdown (ChatGPT, Claude, etc.)
+- **Search** (`src/components/search.tsx`) - Orama full-text search on a static index built at build time
+
+### Styling
+- Tailwind CSS v4 with CSS-driven configuration (no `tailwind.config.*` file)
+- Theme customization in `src/app/global.css` via `@theme` directive
+- Brand colors: ar.io purple `#5427C8`, accent `#DFD6F7`
+
+## Code Standards
+
+### MDX Content
+- Use Fumadocs UI components: `<Cards>`, `<Card>`, `<Steps>`, `<Step>`, `<Tabs>`, `<Tab>`
+- Icons from lucide-react only (imported in mdx-components.tsx)
+- Frontmatter required: `title`, `description`
+- Optional frontmatter: `image`, `icon`, `keywords`, `author`, `full` (full-width layout)
+- Custom components available: `<Tip>`, `<CodeGroup>`, `<Mermaid>`, `<APIPage>`, `<AskArieTooltip>`, `<Image>`
+- Math/LaTeX: Use `$inline$` and `$$block$$` syntax (remark-math + rehype-katex)
+- ESLint is relaxed in `.mdx` files: unused vars, unescaped entities, and `<img>` elements are allowed
+
+### Code Examples
+- Use `fetch` instead of `axios` for HTTP requests
+- Use `ARIO.mainnet()` from '@ar.io/sdk' for ArNS operations
+- Call `setRecord` on ANT instances, not ARIO instances
+- ArNS undernames use underscores: `api_myapp.gateway-url.tld` (not periods)
+
+### Navigation
+- `meta.json` files control page ordering in each directory
+- Format: `{ "pages": ["page-slug", "folder-name", "..."] }`
+- Use `"..."` for auto-discovery of remaining pages
+- Use `"!folder-name"` to exclude a folder from navigation
+- Optional fields: `"icon"` (Lucide icon name), `"defaultOpen"` (expand on load)
+- `build/guides` is automatically sorted alphabetically (configured in `src/lib/source.ts`)
+
+### ESLint
+- Extends: `next/core-web-vitals`, `next/typescript`, `plugin:mdx/recommended`
+- Custom plugin: `validate-jsx-nesting` (enforces proper JSX nesting in components)
+- MDX files have relaxed rules (see MDX Content section above)
+
+## OpenAPI Integration
+
+The site pulls OpenAPI specs from external sources via `scripts/generate-api-docs.ts`:
+- ar-io-node: `https://raw.githubusercontent.com/ar-io/ar-io-node/refs/heads/main/docs/openapi.yaml`
+- turbo upload-service and payment-service
+
+Runtime rendering uses `src/lib/openapi.ts` which fetches the ar-io-node spec directly. Generated API docs go to `content/apis/`. Use `<APIPage>` component in MDX for rendering.
+
+## LLM Text Generation
+
+Scripts generate AI-friendly text files from docs:
+- `public/llms-full.txt` - Complete site content
+- `content/sdks/*/llm.txt` - Per-SDK content (also copied to `public/sdks/`)
+
+## Deployment
+
+- **Production**: Deploys to Arweave via GitHub Actions (`.github/workflows/deploy-to-arweave.yaml`) on pushes to main. Uses permaweb-deploy. Supports manual dispatch with custom ArNS undername.
+- **PR Previews**: `.github/workflows/pr-preview.yaml` deploys previews for PRs that change `content/` or `src/`. Only runs for PRs from the main repo (not forks).

content/apis/ar-io-node/arns.mdx

@@ -13,7 +13,7 @@ _openapi:
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-Get data from the ar.io Gateway Arweave Name System
+Get data from the ar.io Gateway Ar.io Name System
 
 
 <APIPage document={"https://raw.githubusercontent.com/ar-io/ar-io-node/refs/heads/openapi-update/docs/openapi.yaml"} operations={[{"path":"/ar-io/resolver/{name}","method":"get"}]} webhooks={[]} hasHead={true} />

content/build/access/arns.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Arweave Name System (ArNS)"
+title: "Ar.io Name System (ArNS)"
 description: "Assign ArNS names to transaction IDs"
 ---
 
@@ -11,8 +11,8 @@ ArNS is a naming system that allows you to register human-readable names that po
 
 **Example:**
 
-- **Before:** `https://arweave.net/bVLEkL1SOPFCzIYi8T_QNnh17VlDp4RylU6YTwCMVRw`
-- **After:** `https://myapp.arweave.net`
+- **Before:** `https://turbo-gateway.com/bVLEkL1SOPFCzIYi8T_QNnh17VlDp4RylU6YTwCMVRw`
+- **After:** `https://myapp.ar.io`
 
 <Callout type="info">
   **Learn More:** For detailed information about ArNS architecture and how it works, see our [ArNS Documentation](/learn/arns).
@@ -26,10 +26,8 @@ The easiest way to get an ArNS name is via [arns.ar.io](https://arns.ar.io), whi
 - **Turbo Credits** - Use existing Turbo credits
 - **ARIO tokens** - Pay with ARIO cryptocurrency
 
-**Alternative registration methods:**
+**Alternative registration method:**
 
-- **[Wander Chrome Extension](https://chrome.google.com/webstore/detail/wander)** - Browser-based registration
-- **Wander Mobile App** - Register on iOS and Android
 - **ar.io SDK** - Programmatic registration using the `buyRecord` API
 
 ### Using the ar.io SDK
@@ -61,7 +59,7 @@ Once you've set up your ArNS name, fetch data using standard HTTP requests:
 
 ```js
 // Fetch content from your ArNS name
-const response = await fetch("https://my-data.arweave.net");
+const response = await fetch("https://my-data.ar.io");
 
 if (!response.ok) {
   throw new Error(`HTTP error! status: ${response.status}`);
@@ -83,7 +81,7 @@ ArNS provides significant advantages for accessing data on Arweave:
 **Flexible Data Management**
 - **Permanent references** - Keep stable URLs even when updating underlying data
 - **Replaceable data** - Point names to new transaction IDs as content evolves
-- **Undernames** - Organize related content under a single name using underscores (e.g., `v2_myapp.arweave.net`, `docs_myapp.arweave.net`)
+- **Undernames** - Organize related content under a single name using underscores (e.g., `v2_myapp.ar.io`, `docs_myapp.ar.io`)
 
 **Supporting Network Decentralization**
 - ArNS purchases contribute to the protocol balance
@@ -95,7 +93,7 @@ ArNS provides significant advantages for accessing data on Arweave:
 
 <Cards>
   <Card 
-    href="https://arns.app" 
+    href="https://arns.ar.io" 
     title="Buy an ArNS Name"
     icon={<Link />}
   >

content/build/access/fetch-data.mdx

@@ -32,8 +32,8 @@ https://<gateway>/<transaction-id>
 
 **Examples:**
 
-- `https://arweave.net/bVLEkL1SOPFCzIYi8T_QNnh17VlDp4RylU6YTwCMVRw`
-- `https://permagate.io/FguFk5eSth0wO8SKfziYshkSxeIYe7oK9zoPN2PhSc0`
+- `https://turbo-gateway.com/bVLEkL1SOPFCzIYi8T_QNnh17VlDp4RylU6YTwCMVRw`
+- `https://ardrive.net/FguFk5eSth0wO8SKfziYshkSxeIYe7oK9zoPN2PhSc0`
 
 ### Raw Data Endpoint
 
@@ -63,8 +63,8 @@ Ar.io gateways implement security measures by redirecting requests to sandbox su
 
 **What to Expect:**
 
-- Initial request: `https://arweave.net/transaction-id`
-- Redirects to: `https://sandbox.arweave.net/transaction-id` (or similar)
+- Initial request: `https://turbo-gateway.com/transaction-id`
+- Redirects to: `https://sandbox.turbo-gateway.com/transaction-id` (or similar)
 - Final content served from sandbox subdomain
 
 **Important:** Always follow redirects in your applications - the final sandbox URL contains the actual content.
@@ -81,7 +81,7 @@ Ar.io gateways implement security measures by redirecting requests to sandbox su
 
 ```js
 // Fetch data from Arweave (follows redirects automatically)
-const response = await fetch("https://arweave.net/your-transaction-id", {
+const response = await fetch("https://turbo-gateway.com/your-transaction-id", {
   redirect: "follow", // Follow redirects automatically
 });
 
@@ -97,22 +97,22 @@ console.log(data);
 
 ```html
 <!-- Direct image access (browsers handle redirects automatically) -->
-<img src="https://arweave.net/your-image-id" alt="My Image" />
+<img src="https://turbo-gateway.com/your-image-id" alt="My Image" />
 ```
 
 ## Manifests
 
 For organized file collections, use manifests to create friendly path-based URLs:
 
 ```
-https://arweave.net/<manifest-id>/path/to/file
+https://turbo-gateway.com/<manifest-id>/path/to/file
 ```
 
 **Example:**
 
-- `https://arweave.net/X8Qm…AOhA/index.html`
-- `https://arweave.net/X8Qm…AOhA/styles.css`
-- `https://arweave.net/X8Qm…AOhA/assets/logo.png`
+- `https://turbo-gateway.com/X8Qm…AOhA/index.html`
+- `https://turbo-gateway.com/X8Qm…AOhA/styles.css`
+- `https://turbo-gateway.com/X8Qm…AOhA/assets/logo.png`
 
 [Learn more about manifests](/build/upload/manifests)