docs: add directory restructure summary

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: LessUp

docs/DIRECTORY_RESTRUCTURE_SUMMARY.md

@@ -0,0 +1,105 @@
+# Directory Structure Optimization - Summary
+
+## Date: 2026-04-17
+
+## Overview
+Optimized the project directory structure for better organization, maintainability, and alignment with best practices.
+
+## Issues Found and Fixed
+
+### 1. GitHub Pages Files at Root
+**Problem**: `_config.yml`, `index.md`, and `Gemfile` were cluttering the project root.
+**Solution**: Moved all GitHub Pages files to `site/` directory.
+```
+site/
+├── _config.yml
+├── index.md
+└── Gemfile
+```
+
+### 2. Missing Documentation Directories
+**Problem**: `docs/tutorials/` and `docs/assets/` were referenced in docs/README.md but didn't exist.
+**Solution**: Created both directories with appropriate placeholder content.
+
+### 3. No Automation Scripts
+**Problem**: Build, test, and format commands required manual execution.
+**Solution**: Created `scripts/` directory with:
+- `build.sh` - Build the project
+- `test.sh` - Run tests
+- `format.sh` - Format code with clang-format
+
+### 4. Outdated Documentation
+**Problem**: AGENTS.md and README.md didn't reflect the actual structure.
+**Solution**: Updated all documentation to match the new structure.
+
+### 5. GitHub Pages Workflow Configuration
+**Problem**: Workflow was looking for Jekyll files at project root.
+**Solution**: Updated `.github/workflows/pages.yml` to use `site/` as the source directory.
+
+## Final Directory Structure
+
+```
+n-body/
+├── site/                     # GitHub Pages site files [NEW]
+│   ├── _config.yml           # Jekyll configuration
+│   ├── index.md              # Site entry point
+│   └── Gemfile               # Ruby dependencies
+├── specs/                    # Spec documents (Single Source of Truth)
+│   ├── product/              # Product requirements
+│   └── rfc/                  # Technical design documents
+├── docs/                     # User-facing documentation
+│   ├── setup/                # Setup guides
+│   ├── tutorials/            # Tutorials and usage examples [NEW]
+│   ├── architecture/         # Architecture documentation
+│   ├── assets/               # Images and diagrams [NEW]
+│   └── zh-CN/                # Chinese translations
+├── changelog/                # Version changelog
+│   ├── en/                   # English releases
+│   └── zh-CN/                # Chinese releases
+├── include/nbody/            # Public headers
+├── src/                      # Implementation
+│   ├── core/                 # Core simulation logic
+│   ├── cuda/                 # CUDA kernels
+│   ├── render/               # OpenGL rendering
+│   └── utils/                # Utility functions
+├── tests/                    # Test files
+├── examples/                 # Usage examples
+├── scripts/                  # Build and automation scripts [NEW]
+│   ├── build.sh              # Build the project
+│   ├── test.sh               # Run tests
+│   └── format.sh             # Format code
+├── .github/                  # GitHub workflows and templates
+├── .vscode/                  # VS Code settings
+├── AGENTS.md                 # AI agent instructions
+├── CHANGELOG.md              # Changelog summary
+├── CMakeLists.txt            # Build system
+├── CONTRIBUTING.md           # Contribution guidelines
+├── Doxyfile                  # API documentation config
+├── LICENSE                   # License
+├── README.md                 # Project overview (English)
+└── README.zh-CN.md           # Project overview (Chinese)
+```
+
+## Benefits
+
+1. ✅ **Cleaner Root** - Site generation files separated from source code
+2. ✅ **Better Organization** - Logical grouping of related files
+3. ✅ **Automation** - Convenient scripts for common tasks
+4. ✅ **Complete Documentation** - All referenced directories now exist
+5. ✅ **Alignment with Specs** - Structure matches AGENTS.md specification
+6. ✅ **Improved Workflow** - GitHub Pages builds from dedicated `site/` directory
+
+## Verification
+
+- ✅ All documentation updated (AGENTS.md, README.md, docs/README.md)
+- ✅ GitHub Pages workflow updated
+- ✅ Build system unchanged (CMakeLists.txt still works)
+- ✅ Scripts tested and functional
+- ✅ Changes committed and pushed to remote
+
+## Next Steps
+
+- Add tutorial content to `docs/tutorials/`
+- Add architecture diagrams to `docs/assets/`
+- Consider adding `docs.sh` script for API documentation generation
+- Update CI workflow to verify site builds correctly