split data in separate files

CLAUDE.md

@@ -4,11 +4,54 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Purpose
 
-This project aims to create comprehensive API-like documentation of all game elements in Anno 117: Pax Romana. The documentation (docs.md) should catalog buildings, resources, production chains, population tiers, and other game mechanics in a structured, queryable format.
+This project aims to create comprehensive API-like documentation of all game elements in Anno 117: Pax Romana. The documentation catalogs buildings, resources, production chains, population tiers, and other game mechanics in a structured, queryable format.
 
-## Project Status
+## Documentation Structure
 
-This is a new project. The documentation structure and format are yet to be established.
+The documentation is organized in the `docs/` folder:
+
+```
+docs/
+├── index.md              # Main entry point with category links
+├── schemas/              # Entity type definitions
+│   └── _index.md         # Schema overview + individual schema files
+├── population-tiers/     # Tier I-IV documentation
+│   └── _index.md         # Overview + individual tier files
+├── goods/                # All tradeable/consumable items
+│   └── _index.md         # Overview + individual good files
+├── buildings/            # Production, service, infrastructure
+│   └── _index.md         # Overview + individual building files
+├── production-chains/    # Manufacturing sequences
+│   └── _index.md         # Overview + individual chain files
+├── ships/                # Naval units
+│   ├── _index.md         # Ship overview
+│   ├── hulls/            # Ship hull types
+│   └── modules/          # Ship equipment
+├── specialists/          # Character modifiers
+│   └── _index.md         # Overview + individual specialist files
+├── systems/              # Core game mechanics
+│   └── _index.md         # Trade, maintenance, area effects, etc.
+├── monuments/            # Large-scale constructions
+│   └── _index.md         # Overview + individual monument files
+├── troubleshooting/      # Common issues and solutions
+│   └── _index.md         # Overview + playbook files
+└── glossary.md           # Key terms and definitions
+```
+
+### Adding New Documentation
+
+When adding new game entities:
+1. Create a new file in the appropriate category folder
+2. Update the category's `_index.md` to list the new entity
+3. Use the schema defined in `docs/schemas/` for field structure
+4. Add cross-references to related entities
+
+## Data Flow
+
+1. **Scraping:** `python/scraper.py` scrapes pages from anno.land listed in `scraping.md`
+2. **Storage:** Scraped data goes to `scraped_data/*.json`
+3. **Tracking:** `processed.md` tracks which JSON files have been processed
+4. **Documentation:** Processed data is added to appropriate files in `docs/`
 
 ## Goals