# CLAUDE.md

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

## Project Overview

**胡汉三千年 (Hu-Han Three Thousand Years)** is an academic research project that redefines Chinese civilization's world historical significance through theoretical frameworks combining historical research, cultural analysis, and modern technology tools.

## Key Theoretical Frameworks

1. **Y音正统性理论 (Y-Sound Orthodoxy Theory)**: Global patterns of power legitimacy through Y-sounds
2. **北朝宇宙模式 (Northern Dynasty Universe Model)**: Multi-inclusive civilization development paradigm
3. **音韵表意文字系统 (Phonetic-Semantic Writing System)**: Alternative to Chinese characters used by northern nomadic peoples
4. **圐圙词根网络 (Kulue Root Network)**: Systematic network of 32 vocabulary items revealing linguistic patterns

## Common Development Commands

### Documentation
```bash
# Build documentation
./build_docs.sh

# Serve documentation locally
./serve_docs.sh

# Manual Sphinx build (if scripts fail)
cd documentation/sphinx-docs && make html
```

### Environment Setup
```bash
# Install documentation dependencies
pip install -r documentation/sphinx-docs/requirements.txt

# Setup AI tools
./tools/ai-tools/scripts/setup_codex.sh

# Setup visualization tools
./tools/setup/install-viz-tools.sh
```

### Testing
```bash
# Test Milvus GPU integration
python test_milvus_gpu.py

# Test ZSH plugins
./test_plugins.sh
```

## Architecture & Structure

### Core Directories
- `core-theory/`: Theoretical framework definitions and core concepts
- `historical-research/`: Historical analysis and geopolitical studies
- `academic-papers/`: Research methodology and academic publications
- `literary-works/`: Poetry and literary analysis
- `tools/`: AI integration, image processing, and visualization tools
- `documentation/`: Sphinx-based documentation system

### Key Files
- `core-theory/core_definitions.py`: Central theoretical framework definitions
- `core-theory/phonetic_semantic_framework.md`: Phonetic-semantic writing system
- `core-theory/heaven_earth_logic_framework.md`: "Heaven-Earth connection" philosophy
- `core-theory/kulue_root_network.md`: Kulue root word network analysis

### Documentation System
- **Sphinx-based** with multilingual support (Chinese/English)
- **Two configurations**: `documentation/sphinx-docs/conf.py` (main) and `documentation/docs/conf.py` (alternative)
- **MyST parser** for Markdown support
- **Read the Docs theme** with customizations
- **Automated CI/CD** via GitHub Actions and Gitea workflows

### Virtual Environments
- `gpu_test_env/`: GPU testing environment
- `sphinx-env/`: Documentation building
- `config/.venv/`: Jupyter and development tools
- `tools/ai-tools/codex_env/`: AI tools integration

## Development Guidelines

### When Working with Theoretical Content
- Maintain academic rigor and citation standards
- Use "纯逻辑考古 (pure logic archaeology)" methodology
- Apply "多重验证 (multiple validation)" approach (linguistic + historical + geographical + cultural)
- Focus on "文明系统演化 (civilization system evolution)" framework

### When Working with Technical Tools
- Test GPU integrations with `test_milvus_gpu.py`
- Use appropriate virtual environments for different tools
- Follow Sphinx documentation standards for new content
- Maintain CI/CD compatibility for automated builds

### When Working with Documentation
- Build and test documentation before committing
- Use MyST Markdown syntax for enhanced features
- Maintain both Chinese and English content where applicable
- Follow existing academic formatting standards

## Recent Research Focus

The project recently achieved a breakthrough in "Japanese phallic worship originating from Northern Wei dynasty" (commit b6105b6), combining:
- Textual analysis of character variants
- Architectural evidence (Yingxian Wooden Pagoda)
- Institutional cultural transmission analysis (386-645 CE)

## Important Notes

- This is primarily a **research and documentation project**, not a software application
- **Git LFS** is enabled for large assets (3body-related materials)
- **Academic integrity** is paramount - maintain proper attribution and methodology
- **Cultural sensitivity** required when handling historical and cultural analysis
- **Strategic focus** on addressing China-US strategic misjudgment through cultural understanding