docs: restructure documentation for improved clarity and navigation

Reorganize documentation into user-focused, developer-focused, and deployment-focused sections.

**New structure:**
- Root: README.md (streamlined), QUICK_START.md, API_REFERENCE.md
- docs/user-guide/: configuration, API usage, integrations, troubleshooting
- docs/developer/: contributing, development setup, testing, architecture
- docs/deployment/: Docker deployment, production checklist, monitoring
- docs/reference/: environment variables, MCP tools, data formats

**Changes:**
- Streamline README.md from 831 to 469 lines
- Create QUICK_START.md for 5-minute onboarding
- Create API_REFERENCE.md as single source of truth for API
- Remove 9 outdated specification docs (v0.2.0 API design)
- Remove DOCKER_API.md (content consolidated into new structure)
- Remove docs/plans/ directory with old design documents
- Update CLAUDE.md with documentation structure guide
- Remove orchestration-specific references

**Benefits:**
- Clear entry points for different audiences
- No content duplication
- Better discoverability through logical hierarchy
- All content reflects current v0.3.0 API

docs/developer/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to AI-Trader
+
+Guidelines for contributing to the project.
+
+---
+
+## Development Setup
+
+See [development-setup.md](development-setup.md)
+
+---
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create feature branch: `git checkout -b feature/my-feature`
+3. Make changes
+4. Run tests: `pytest tests/`
+5. Update documentation
+6. Commit: `git commit -m "Add feature: description"`
+7. Push: `git push origin feature/my-feature`
+8. Create Pull Request
+
+---
+
+## Code Style
+
+- Follow PEP 8 for Python
+- Use type hints
+- Add docstrings to public functions
+- Keep functions focused and small
+
+---
+
+## Testing Requirements
+
+- Unit tests for new functionality
+- Integration tests for API changes
+- Maintain test coverage >80%
+
+---
+
+## Documentation
+
+- Update README.md for new features
+- Add entries to CHANGELOG.md
+- Update API_REFERENCE.md for endpoint changes
+- Include examples in relevant guides

docs/developer/adding-models.md

@@ -0,0 +1,69 @@
+# Adding Custom AI Models
+
+How to add and configure custom AI models.
+
+---
+
+## Basic Setup
+
+Edit `configs/default_config.json`:
+
+```json
+{
+  "models": [
+    {
+      "name": "Your Model Name",
+      "basemodel": "provider/model-id",
+      "signature": "unique-identifier",
+      "enabled": true
+    }
+  ]
+}
+```
+
+---
+
+## Examples
+
+### OpenAI Models
+
+```json
+{
+  "name": "GPT-4",
+  "basemodel": "openai/gpt-4",
+  "signature": "gpt-4",
+  "enabled": true
+}
+```
+
+### Anthropic Claude
+
+```json
+{
+  "name": "Claude 3.7 Sonnet",
+  "basemodel": "anthropic/claude-3.7-sonnet",
+  "signature": "claude-3.7-sonnet",
+  "enabled": true,
+  "openai_base_url": "https://api.anthropic.com/v1",
+  "openai_api_key": "your-anthropic-key"
+}
+```
+
+### Via OpenRouter
+
+```json
+{
+  "name": "DeepSeek",
+  "basemodel": "deepseek/deepseek-chat",
+  "signature": "deepseek",
+  "enabled": true,
+  "openai_base_url": "https://openrouter.ai/api/v1",
+  "openai_api_key": "your-openrouter-key"
+}
+```
+
+---
+
+## Field Reference
+
+See [docs/user-guide/configuration.md](../user-guide/configuration.md#model-configuration-fields) for complete field descriptions.

docs/developer/architecture.md

@@ -0,0 +1,68 @@
+# Architecture
+
+System design and component overview.
+
+---
+
+## Component Diagram
+
+See README.md for architecture diagram.
+
+---
+
+## Key Components
+
+### FastAPI Server (`api/main.py`)
+- REST API endpoints
+- Request validation
+- Response formatting
+
+### Job Manager (`api/job_manager.py`)
+- Job lifecycle management
+- SQLite operations
+- Concurrency control
+
+### Simulation Worker (`api/simulation_worker.py`)
+- Background job execution
+- Date-sequential, model-parallel orchestration
+- Error handling
+
+### Model-Day Executor (`api/model_day_executor.py`)
+- Single model-day execution
+- Runtime config isolation
+- Agent invocation
+
+### Base Agent (`agent/base_agent/base_agent.py`)
+- Trading session execution
+- MCP tool integration
+- Position management
+
+### MCP Services (`agent_tools/`)
+- Math, Search, Trade, Price tools
+- Internal HTTP servers
+- Localhost-only access
+
+---
+
+## Data Flow
+
+1. API receives trigger request
+2. Job Manager validates and creates job
+3. Worker starts background execution
+4. For each date (sequential):
+   - For each model (parallel):
+     - Executor creates isolated runtime config
+     - Agent executes trading session
+     - Results stored in database
+5. Job status updated
+6. Results available via API
+
+---
+
+## Anti-Look-Ahead Controls
+
+- `TODAY_DATE` in runtime config limits data access
+- Price queries filter by date
+- Search results filtered by publication date
+
+See [CLAUDE.md](../../CLAUDE.md) for implementation details.

docs/developer/database-schema.md

@@ -0,0 +1,94 @@
+# Database Schema
+
+SQLite database schema reference.
+
+---
+
+## Tables
+
+### jobs
+Job metadata and overall status.
+
+```sql
+CREATE TABLE jobs (
+    job_id TEXT PRIMARY KEY,
+    config_path TEXT NOT NULL,
+    status TEXT CHECK(status IN ('pending', 'running', 'completed', 'partial', 'failed')),
+    date_range TEXT,  -- JSON array
+    models TEXT,      -- JSON array
+    created_at TEXT,
+    started_at TEXT,
+    completed_at TEXT,
+    total_duration_seconds REAL,
+    error TEXT
+);
+```
+
+### job_details
+Per model-day execution details.
+
+```sql
+CREATE TABLE job_details (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id TEXT,
+    model_signature TEXT,
+    trading_date TEXT,
+    status TEXT CHECK(status IN ('pending', 'running', 'completed', 'failed')),
+    start_time TEXT,
+    end_time TEXT,
+    duration_seconds REAL,
+    error TEXT,
+    FOREIGN KEY (job_id) REFERENCES jobs(job_id) ON DELETE CASCADE
+);
+```
+
+### positions
+Trading position records with P&L.
+
+```sql
+CREATE TABLE positions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id TEXT,
+    date TEXT,
+    model TEXT,
+    action_id INTEGER,
+    action_type TEXT,
+    symbol TEXT,
+    amount INTEGER,
+    price REAL,
+    cash REAL,
+    portfolio_value REAL,
+    daily_profit REAL,
+    daily_return_pct REAL,
+    created_at TEXT
+);
+```
+
+### holdings
+Portfolio holdings breakdown per position.
+
+```sql
+CREATE TABLE holdings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    position_id INTEGER,
+    symbol TEXT,
+    quantity REAL,
+    FOREIGN KEY (position_id) REFERENCES positions(id) ON DELETE CASCADE
+);
+```
+
+### price_data
+Cached historical price data.
+
+### price_coverage
+Data availability tracking per symbol.
+
+### reasoning_logs
+AI decision reasoning (when enabled).
+
+### tool_usage
+MCP tool usage statistics.
+
+---
+
+See `api/database.py` for complete schema definitions.

docs/developer/development-setup.md

@@ -0,0 +1,71 @@
+# Development Setup
+
+Local development without Docker.
+
+---
+
+## Prerequisites
+
+- Python 3.10+
+- pip
+- virtualenv
+
+---
+
+## Setup Steps
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/Xe138/AI-Trader.git
+cd AI-Trader
+```
+
+### 2. Create Virtual Environment
+
+```bash
+python3 -m venv venv
+source venv/bin/activate  # Linux/Mac
+# venv\Scripts\activate  # Windows
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Configure Environment
+
+```bash
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+### 5. Start MCP Services
+
+```bash
+cd agent_tools
+python start_mcp_services.py &
+cd ..
+```
+
+### 6. Start API Server
+
+```bash
+python -m uvicorn api.main:app --reload --port 8080
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Project Structure
+
+See [CLAUDE.md](../../CLAUDE.md) for complete project structure.

docs/developer/testing.md

@@ -0,0 +1,64 @@
+# Testing Guide
+
+Guide for testing AI-Trader during development.
+
+---
+
+## Automated Testing
+
+### Docker Build Validation
+
+```bash
+chmod +x scripts/*.sh
+bash scripts/validate_docker_build.sh
+```
+
+Validates:
+- Docker installation
+- Environment configuration
+- Image build
+- Container startup
+- Health endpoint
+
+### API Endpoint Testing
+
+```bash
+bash scripts/test_api_endpoints.sh
+```
+
+Tests all API endpoints with real simulations.
+
+---
+
+## Unit Tests
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run tests
+pytest tests/ -v
+
+# With coverage
+pytest tests/ -v --cov=api --cov-report=term-missing
+
+# Specific test file
+pytest tests/unit/test_job_manager.py -v
+```
+
+---
+
+##  Integration Tests
+
+```bash
+# Run integration tests only
+pytest tests/integration/ -v
+
+# Test with real API server
+docker-compose up -d
+pytest tests/integration/test_api_endpoints.py -v
+```
+
+---
+
+For detailed testing procedures, see root [TESTING_GUIDE.md](../../TESTING_GUIDE.md).