Skip to content

CLAUDE.md

Latest commit

 

History

History
96 lines (75 loc) · 3.83 KB

CLAUDE.md

File metadata and controls

96 lines (75 loc) · 3.83 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Quilibrium documentation website built with Docusaurus 3.8.0. The site is deployed to https://docs.quilibrium.com and contains comprehensive documentation for the Quilibrium network.

Development Commands

Essential Commands

  • yarn start - Start local development server with hot reload
  • yarn build - Build production-ready static files
  • yarn typecheck - Run TypeScript type checking
  • yarn serve - Serve production build locally for testing
  • yarn deploy - Deploy to GitHub Pages (use USE_SSH=true yarn deploy for SSH)
  • yarn clear - Clear Docusaurus caches and generated files

Environment Setup

Create a .env file from .env.example:

  • ENABLE_API_TESTER=true - Enable API tester functionality

Architecture

Technology Stack

  • Framework: Docusaurus 3.8.0 with React 18
  • Language: TypeScript
  • Styling: Tailwind CSS with custom plugin
  • Search: Lunr local search
  • Visualizations: D3.js for technical diagrams

Documentation Structure

The docs are organized into 6 main sections (auto-generated sidebars from directories):

  • discover/ - Introduction, FAQ, tokenomics
  • learn/ - Technical deep dives
  • build/ - Developer guides
  • protocol/ - Protocol specifications
  • api/ - API documentation
  • run-node/ - Node operation guides

Key Configuration Files

  • docusaurus.config.ts - Main site configuration
  • sidebars.ts - Sidebar structure (uses autogenerated sidebars)
  • tailwind.config.js - Tailwind CSS configuration

Documentation Guidelines

General Rules

  • Do not directly copy text from AWS documentation - always paraphrase and relate to Q concepts
  • Group related concepts together (e.g., all container information in Container section)
  • Write one sentence per line in markdown for easier PR reviews

QStorage API Documentation

  • S3 Compatibility: QStorage implements AWS S3 API with specific modifications
  • Encryption Headers:
    • X-Amz-Server-Side-Encryption: AES256 - Uses QKMS for encryption
    • X-Amz-Server-Side-Encryption-Customer-Algorithm: AES256 - User-managed keys
  • Host URLs: Use format q-storage-s3.q.network (not localhost:5599)
  • Unsupported Features: Directory buckets, bucket replication, encryption with KMS key IDs

Q Services API Documentation

  • Service Subdomains: Format as <ServiceName>.q.network (e.g., q-storage-s3.q.network)
  • Document Structure: Follow "What is" → "Benefits" → "Deployment Options" → "Regional Deployment"
  • Component Usage: Use <APIInfo /> and <SimpleTable /> for API endpoints
  • Data Types: Format as string | integer | boolean (lowercase, pipe-separated)
  • API Changes: Document data type and constraint changes carefully

Interactive Components

The docs include custom React components for:

  • API testing (when enabled via environment variable)
  • Force graph visualizations
  • Interactive diagrams

AI Agent Workflow

This project uses an .agents/ folder for AI-generated documentation, task tracking, bug reports, and reports. See .agents/AGENTS.md for full guidelines.

Quick Reference

  • Tasks: .agents/tasks/ (completed → .agents/tasks/.done/)
  • Bugs: .agents/bugs/ (solved → .agents/bugs/.solved/)
  • Docs: .agents/docs/features/
  • Reports: .agents/reports/ (completed → .agents/reports/.done/)
  • Index: Run python .agents/update-index.py after changes to regenerate .agents/INDEX.md

Deployment

License

Documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).

Updated: 2026-02-11 UTC