codemap generation

CLAUDE.md

@@ -1,9 +1,224 @@
-- The documentation of the project is located in docs/ directory;
-- Get following files in context before doing anything else:
-  - docs\CLAUDE.md
-  - docs\CODE_OF_CONDUCT.md
-  - project.godot
-- Use TDD methodology for development;
-- Use static data types;
-- Keep documentation up to date;
-- Always run tests `./tools/run_development.py --yaml --silent`;
+# CLAUDE.md
+
+Guidance for Claude Code (claude.ai/code) when working with this repository.
+
+## Required Context Files
+
+Before doing anything else, get the following files in context:
+- **docs/ARCHITECTURE.md** - System design, autoloads, architectural patterns
+- **docs/CODE_OF_CONDUCT.md** - Coding standards, naming conventions, best practices
+- **project.godot** - Input actions and autoload definitions
+
+## Auto-Generated Machine-Readable Documentation
+
+**⚠️ IMPORTANT**: Before starting development, generate fresh code maps for current codebase context:
+
+```bash
+python tools/generate_code_map.py
+```
+
+This generates machine-readable JSON maps optimized for LLM consumption in `.llm/` directory (git-ignored).
+
+**When to use**:
+- At the start of every development session
+- After major refactoring or adding new files
+- When you need current codebase structure/API reference
+
+## Core Development Rules
+
+- **Use TDD methodology** for development
+- **Use static data types** in all GDScript code
+- **Keep documentation up to date** when making changes
+- **Always run tests**: `./tools/run_development.py --yaml --silent`
+
+## Code Maps (LLM Development Workflow)
+
+Machine-readable code intelligence for LLM-assisted development.
+
+### Quick Reference: Which Map to Load?
+
+| Task | Load This Map | Size | Contains |
+|------|---------------|------|----------|
+| Adding/modifying functions | `code_map_api.json` | ~47KB | Function signatures, parameters, return types |
+| System architecture work | `code_map_architecture.json` | ~32KB | Autoloads, design patterns, structure |
+| Signal/scene connections | `code_map_flows.json` | ~7KB | Signal chains, scene transitions |
+| Input validation/errors | `code_map_security.json` | ~12KB | Validation patterns, error handling |
+| Asset/resource management | `code_map_assets.json` | ~12KB | Dependencies, preloads, licensing |
+| Code metrics/statistics | `code_map_metadata.json` | ~300B | Stats, complexity metrics |
+
+### Generated Files (Git-Ignored)
+
+**Location**: `.llm/` directory (automatically excluded from git)
+
+**Format**: All JSON files are minified (no whitespace) for optimal LLM token efficiency.
+
+**Total size**: ~110KB if loading all maps (recommended: load only what you need)
+
+### Generating Code Maps
+
+```bash
+# Generate everything (default behavior - maps + diagrams + docs + metrics)
+python tools/generate_code_map.py
+
+# Generate only specific outputs
+python tools/generate_code_map.py --diagrams  # Diagrams only
+python tools/generate_code_map.py --docs      # Documentation only
+python tools/generate_code_map.py --metrics   # Metrics dashboard only
+
+# Explicitly generate all (same as no arguments)
+python tools/generate_code_map.py --all
+
+# Via development workflow tool
+python tools/run_development.py --codemap
+
+# Custom output location (single JSON file)
+python tools/generate_code_map.py --output custom_map.json
+
+# Skip PNG rendering (Mermaid source only)
+python tools/generate_code_map.py --diagrams --no-render
+```
+
+**New Features**:
+- **Diagrams**: Auto-generated diagrams (architecture, signal flows, scene hierarchy, dependencies) rendered to PNG using matplotlib
+- **Documentation**: Human-readable markdown docs with embedded diagrams (AUTOLOADS_API.md, SIGNALS_CATALOG.md, FUNCTION_INDEX.md, etc.)
+- **Metrics**: Markdown dashboard with statistics charts and complexity analysis
+
+### When to Regenerate
+
+Regenerate code maps when:
+- **Starting an LLM-assisted development session** - Get fresh context
+- **After adding new files** - Include new code in maps
+- **After major refactoring** - Update structure information
+- **After changing autoloads** - Capture architectural changes
+- **When onboarding new developers** - Provide comprehensive context
+
+### LLM Development Workflow
+
+1. **Generate maps**: `python tools/generate_code_map.py`
+
+2. **Load relevant maps**: Choose based on your task
+
+   **For API/Function development**:
+   ```
+   Load: .llm/code_map_api.json (~47KB)
+   Contains: All function signatures, parameters, return types, docstrings
+   ```
+
+   **For architecture/system design**:
+   ```
+   Load: .llm/code_map_architecture.json (~32KB)
+   Contains: Autoloads, design patterns, system structure
+   ```
+
+   **For signal/scene work**:
+   ```
+   Load: .llm/code_map_flows.json (~7KB)
+   Contains: Signal chains, scene transitions, connections
+   ```
+
+   **For security/validation**:
+   ```
+   Load: .llm/code_map_security.json (~12KB)
+   Contains: Input validation patterns, error handling
+   ```
+
+   **For assets/resources**:
+   ```
+   Load: .llm/code_map_assets.json (~12KB)
+   Contains: Asset dependencies, preloads, licensing
+   ```
+
+   **For metrics/stats**:
+   ```
+   Load: .llm/code_map_metadata.json (~300B)
+   Contains: Code statistics, complexity metrics
+   ```
+
+3. **Use selectively**:
+   - Load only maps relevant to current task
+   - Reduces token usage and improves focus
+   - Can always add more context later
+   - Total size if loading all: ~110KB minified JSON
+
+## Essential Coding Patterns
+
+### Scene Management
+```gdscript
+# ✅ Correct - Use GameManager
+GameManager.start_game_with_mode("match3")
+
+# ❌ Wrong - Never call directly
+get_tree().change_scene_to_file("res://scenes/game/Game.tscn")
+```
+
+### Logging
+```gdscript
+# ✅ Correct - Use DebugManager with categories
+DebugManager.log_info("Scene loaded successfully", "GameManager")
+DebugManager.log_error("Failed to load resource", "AssetLoader")
+
+# ❌ Wrong - Never use plain print/push_error
+print("Scene loaded")  # No structure, no category
+push_error("Failed")   # Missing context
+```
+
+### Memory Management
+```gdscript
+# ✅ Correct - Use queue_free()
+for child in children_to_remove:
+    child.queue_free()
+await get_tree().process_frame  # Wait for cleanup
+
+# ❌ Wrong - Never use free()
+child.free()  # Immediate deletion causes crashes
+```
+
+### Input Validation
+```gdscript
+# ✅ Correct - Validate all inputs
+func set_volume(value: float) -> bool:
+    if value < 0.0 or value > 1.0:
+        DebugManager.log_error("Invalid volume: " + str(value), "Settings")
+        return false
+    # Process validated input
+
+# ❌ Wrong - No validation
+func set_volume(value: float):
+    volume = value  # Could be negative or > 1.0
+```
+
+See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) for complete coding standards.
+
+## Quick Reference
+
+- **Development commands**: See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- **Testing protocols**: See [docs/TESTING.md](docs/TESTING.md)
+- **Architecture patterns**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- **Naming conventions**: See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md#naming-convention-quick-reference)
+- **Quality checklist**: See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md#code-quality-checklist)
+
+## Project Structure
+
+```
+skelly/
+├── src/autoloads/          # Global manager singletons
+├── scenes/game/gameplays/  # Gameplay mode implementations
+├── scenes/ui/              # Menu scenes and components
+├── assets/                 # Audio, sprites, fonts (kebab-case)
+├── data/                   # Godot resource files (.tres)
+├── docs/                   # Documentation
+├── tests/                  # Test scripts
+└── tools/                  # Development tools
+```
+
+See [docs/MAP.md](docs/MAP.md) for complete file organization.
+
+## Key Files to Understand
+
+- `src/autoloads/GameManager.gd` - Scene transitions with race condition protection
+- `src/autoloads/SaveManager.gd` - Save system with security features
+- `src/autoloads/SettingsManager.gd` - Settings with input validation
+- `src/autoloads/DebugManager.gd` - Unified logging and debug UI
+- `scenes/game/Game.gd` - Main game scene, modular gameplay system
+- `scenes/game/gameplays/Match3Gameplay.gd` - Match-3 implementation
+- `project.godot` - Input actions and autoload definitions