Update suitbuilder documentation to reflect production-ready status

- Replace outdated CLAUDE.md suitbuilder section with concise production-ready summary
- Remove incorrect claims about spell system not being implemented
- Create detailed architecture document at docs/plans/2026-02-09-suitbuilder-architecture.md
- Document spell bitmap system, locked slots, suit summary, and SSE streaming
- Add future enhancement roadmap (spell improvements, new builders, advanced features)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,140 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Dereth Tracker is a real-time telemetry service for game world tracking. It's a FastAPI-based WebSocket and HTTP API service that ingests player position/stats data via plugins and provides live map visualization through a web interface.
+
+## Key Components
+
+### Main Service (main.py)
+- WebSocket endpoint `/ws/position` receives telemetry and inventory events
+- Routes inventory events to inventory service via HTTP
+- Handles real-time player tracking and map updates
+
+### Inventory Service (inventory-service/main.py)
+- Separate FastAPI service for inventory management
+- Processes inventory JSON into normalized PostgreSQL tables
+- Provides search API with advanced filtering and sorting
+- Uses comprehensive enum database for translating game IDs to readable names
+
+### Database Architecture
+- **Telemetry DB**: TimescaleDB for time-series player tracking data
+- **Inventory DB**: PostgreSQL with normalized schema for equipment data
+  - `items`: Core item properties
+  - `item_combat_stats`: Armor level, damage bonuses
+  - `item_enhancements`: Material, item sets, tinkering
+  - `item_spells`: Spell names and categories
+  - `item_raw_data`: Original JSON for complex queries
+
+## Memories and Known Bugs
+
+* Fixed: Material names now properly display (e.g., "Gold Celdon Girth" instead of "Unknown_Material_Gold Celdon Girth")
+* Fixed: Slot column shows "-" instead of "Unknown" for items without slot data
+* Fixed: All 208 items in Larsson's inventory now process successfully (was 186 with 22 SQL type errors)
+* Added: Type column in inventory search using object_classes enum for accurate item type classification
+* Note: ItemType data is inconsistent in JSON - using ObjectClass as primary source for Type column
+
+## Recent Fixes (September 2025)
+
+### Portal Coordinate Rounding Fix ✅ RESOLVED
+* **Problem**: Portal insertion failed with duplicate key errors due to coordinate rounding mismatch
+* **Root Cause**: Code used 2 decimal places (`ROUND(ns::numeric, 2)`) but database constraint used 1 decimal place
+* **Solution**: Changed all portal coordinate checks to use 1 decimal place to match DB constraint
+* **Result**: 98% reduction in duplicate key errors (from 600+/min to ~11/min)
+* **Location**: `main.py` lines ~1989, 1996, 2025, 2047
+
+### Character Display Issues ✅ RESOLVED
+* **Problem**: Some characters (e.g., "Crazed n Dazed") not appearing in frontend
+* **Root Cause**: Database connection pool exhaustion from portal error spam
+* **Solution**: Fixed portal errors to reduce database load
+* **Result**: Characters now display correctly after portal fix
+
+### Docker Container Deployment
+* **Issue**: Code changes require container rebuild with `--no-cache` flag
+* **Command**: `docker compose build --no-cache dereth-tracker`
+* **Reason**: Docker layer caching can prevent updated source code from being copied
+
+## Current Known Issues
+
+### Minor Portal Race Conditions
+* **Status**: ~11 duplicate key errors per minute (down from 600+)
+* **Cause**: Multiple players discovering same portal simultaneously
+* **Impact**: Minimal - errors are caught and handled gracefully
+* **Handling**: Try/catch in code logs as debug messages and updates portal timestamp
+* **Potential Fix**: PostgreSQL ON CONFLICT DO UPDATE (upsert pattern) would eliminate completely
+
+### Database Initialization Warnings
+* **TimescaleDB Hypertable**: `telemetry_events` fails to become hypertable due to primary key constraint
+* **Impact**: None - table works as regular PostgreSQL table
+* **Warning**: "cannot create a unique index without the column 'timestamp'"
+
+### Connection Pool Under Load
+* **Issue**: Database queries can timeout when connection pool is exhausted
+* **Symptom**: Characters may not appear during high error load
+* **Mitigation**: Portal error fix significantly reduced this issue
+
+## Equipment Suit Builder
+
+### Status: PRODUCTION READY
+
+Real-time equipment optimization engine for building optimal character loadouts by searching across multiple characters' inventories (mules). Uses Mag-SuitBuilder constraint satisfaction algorithms.
+
+**Core Features:**
+- Multi-character inventory search across 100+ characters, 25,000+ items
+- Armor set constraints (primary 5-piece + secondary 4-piece set support)
+- Cantrip/ward spell optimization with bitmap-based overlap detection
+- Crit damage rating optimization
+- Locked slots with set/spell preservation across searches
+- Real-time SSE streaming with progressive phase updates
+- Suit summary with copy-to-clipboard functionality
+- Stable deterministic sorting for reproducible results
+
+**Access:** `/suitbuilder.html`
+
+**Architecture Details:** See `docs/plans/2026-02-09-suitbuilder-architecture.md`
+
+### Known Limitations
+- Slot-aware spell filtering not yet implemented (e.g., underclothes have limited spell pools but system treats all slots equally)
+- All spells weighted equally (no priority/importance weighting yet)
+- See architecture doc for future enhancement roadmap
+
+## Technical Notes for Development
+
+### Database Performance
+- Connection pool: 5-20 connections (configured in `db_async.py`)
+- Under heavy error load, pool exhaustion can cause 2-minute query timeouts
+- Portal error fix significantly improved database performance
+
+### Docker Development Workflow
+1. **Code Changes**: Edit source files locally
+2. **Rebuild**: `docker compose build --no-cache dereth-tracker` (required for code changes)
+3. **Deploy**: `docker compose up -d dereth-tracker`
+4. **Debug**: `docker logs mosswartoverlord-dereth-tracker-1` and `docker logs dereth-db`
+
+### Frontend Architecture
+- **Main Map**: `static/index.html` - Real-time player tracking
+- **Inventory Search**: `static/inventory.html` - Advanced item filtering
+- **Suitbuilder**: `static/suitbuilder.html` - Equipment optimization interface
+- **All static files**: Served directly by FastAPI StaticFiles
+
+### DOM Optimization Status ✅ COMPLETE (September 2025)
+* **Achievement**: 100% DOM element reuse with zero element creation after initial render
+* **Performance**: ~5ms render time for 69 players, eliminated 4,140+ elements/minute creation
+* **Implementation**: Element pooling system with player name mapping for O(1) lookup
+* **Monitoring**: Color-coded console output (✨ green = optimized, ⚡ yellow = partial, 🔥 red = poor)
+* **Status**: Production ready - achieving perfect element reuse consistently
+
+**Current Render Stats**:
+- ✅ This render: 0 dots created, 69 reused | 0 list items created, 69 reused
+- ✅ Lifetime: 69 dots created, 800+ reused | 69 list items created, 800+ reused
+
+**Remaining TODO**:
+- ❌ Fix CSS Grid layout for player sidebar (deferred per user request)
+- ❌ Extend optimization to trails and portal rendering
+- ❌ Add memory usage tracking
+
+### WebSocket Endpoints
+- `/ws/position`: Plugin telemetry, inventory, portal, rare events (authenticated)
+- `/ws/live`: Browser client commands and live updates (unauthenticated)