commit 0f370ec0899371b86b3b9a5d65fcb5af747c4f86
Author: truetype <max.mauri@gmail.com>
Date:   Sun Feb 8 14:41:16 2026 +0100

    first phase commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..903bb03
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+# MUD AI Player
+
+An autonomous AI player for MUD (Multi-User Dungeon) text-based games.
+
+## Features
+
+- 🤖 **Autonomous Gameplay**: Simulates a human player from character creation to endgame
+- 🗺️ **Auto-Mapping**: Builds a complete map of the MUD world with hybrid storage (SQLite + Memvid)
+- ⚔️ **Combat AI**: Intelligent combat decisions, target selection, and survival tactics
+- 📜 **Quest System**: Automatically detects, plans, and completes quests
+- 🔍 **Semantic Search**: Find locations using natural language queries
+- 📊 **Progression Optimizer**: Finds optimal grinding spots and equipment upgrades
+
+## Architecture
+
+The application is built with a modular architecture:
+
+- **Core**: Telnet client, ANSI parser, text parser, game state
+- **Modules**:
+  - Character Creator: Stats rolling, class/race selection
+  - Auto-Mapper: World mapping with hybrid storage (SQLite + Memvid)
+  - Decision Engine: AI decision-making, combat AI, goal management
+  - Quest System: Quest detection, planning, execution
+  - Progression Optimizer: Grinding optimization, equipment analysis
+
+## Installation
+
+### Using Poetry (Recommended)
+
+```bash
+# Install Poetry if not already installed
+pip install poetry
+
+# Install dependencies
+poetry install
+
+# Activate virtual environment
+poetry shell
+```
+
+### Using pip
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+## Configuration
+
+1. Copy the example configuration:
+   ```bash
+   cp examples/config.example.yaml config.yaml
+   ```
+
+2. Edit `config.yaml` with your MUD server details:
+   ```yaml
+   mud:
+     host: "your-mud-server.com"
+     port: 4000
+     username: "your_username"
+     password: "your_password"
+   ```
+
+## Usage
+
+```bash
+# Run the AI player
+python -m src.main
+
+# Run with custom config
+python -m src.main --config custom_config.yaml
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+```
+
+## Project Structure
+
+```
+mud-ai-player/
+├── src/                    # Source code
+│   ├── core/              # Core components
+│   ├── modules/           # Specialized modules
+│   ├── utils/             # Utilities
+│   └── config/            # Configuration management
+├── data/                  # Persistent storage
+│   ├── maps/             # World maps (SQLite + Memvid)
+│   ├── characters/       # Character saves
+│   └── logs/             # Game logs
+├── tests/                # Test suite
+├── docs/                 # Documentation
+└── examples/             # Example configurations
+```
+
+## Development
+
+```bash
+# Format code
+black src/ tests/
+
+# Lint code
+ruff check src/ tests/
+
+# Run tests with watch
+pytest-watch
+```
+
+## Documentation
+
+See the `docs/` directory for detailed documentation:
+
+- [Architecture](docs/architecture.md)
+- [Configuration Guide](docs/configuration.md)
+- [Development Guide](docs/development.md)
+- [API Reference](docs/api_reference.md)
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please read the development guide before submitting PRs.
+
+## Disclaimer
+
+This is an educational project. Please respect the rules and terms of service of any MUD you connect to. Some MUDs prohibit automated players.