diff --git a/docs/plans/2026-01-30-suitbuilder-design.md b/docs/plans/2026-01-30-suitbuilder-design.md
new file mode 100644
index 00000000..794e19d2
--- /dev/null
+++ b/docs/plans/2026-01-30-suitbuilder-design.md
@@ -0,0 +1,216 @@
+# Suitbuilder Design Document
+
+**Date:** 2026-01-30
+**Status:** In Progress
+**Reference:** `magsuitalgo.md` (detailed MagSuitBuilder algorithm analysis)
+
+---
+
+## Section 1: Problem Statement & Goals
+
+### What is Suitbuilder?
+
+Suitbuilder helps players find the best equipment combination from their inventory across multiple "mule" characters. In Asheron's Call, players have many characters storing thousands of armor pieces, jewelry, and accessories. Finding the optimal combination manually is impractical.
+
+### Why is this hard?
+
+The naive approach would check every possible combination: if you have 50 items per slot across 17 equipment slots, that's 50^17 combinations - more than atoms in the universe. MagSuitBuilder solved this with smart algorithms, and we're replicating that approach.
+
+### Main Goal - Priority Order
+
+Given user constraints, find equipment combinations that:
+
+1. **Complete armor set bonuses** (5 pieces primary set + 4 pieces secondary set) - HIGHEST PRIORITY
+2. **Cover all required spells/cantrips** without duplicates
+3. **Maximize armor protection** - LOWEST PRIORITY (tiebreaker)
+
+### Why we're doing this
+
+The original MagSuitBuilder is a Windows desktop app. We want this functionality in our web-based Dereth Tracker so players can search their inventories from any browser.
+
+---
+
+## Section 2: Algorithm Overview
+
+### The Bucket Approach
+
+Instead of checking all item combinations, we organize items into "buckets" by equipment slot (Head, Chest, Hands, etc.). Then we search through buckets one at a time using recursion with backtracking.
+
+### How it works
+
+1. **Create buckets** - One bucket per equipment slot (11 armor slots + jewelry slots)
+2. **Sort buckets** - Process smallest buckets first (fewer branches to explore)
+3. **Recursive search** - Try each item in bucket 1, then recurse to bucket 2, etc.
+4. **Backtrack** - When a branch fails constraints, undo and try next item
+5. **Skip allowed** - Can skip a slot entirely (incomplete suit better than constraint violation)
+
+### Why this is fast
+
+- Bucket with 20 items × bucket with 15 items × bucket with 10 items = 3,000 combinations
+- vs. checking every item against every other item = millions of combinations
+
+### Two-Phase Search (from MagSuitBuilder)
+
+1. **Phase 1 - ArmorSearcher**: Find optimal armor combinations (enforces set constraints)
+2. **Phase 2 - AccessorySearcher**: Add jewelry to complete spell coverage
+
+### Key Data Structures
+
+- **Spell Bitmap**: 32-bit integer where each bit = one spell. Overlap detection is instant via bitwise OR
+- **Coverage Mask**: Tracks which body areas are covered to prevent conflicts
+- **Set Counter**: Tracks pieces per armor set (max 5 primary, 4 secondary)
+
+---
+
+## Section 3: Current Implementation State
+
+### What's Working
+
+- **Spell Bitmap System** - Correctly implements O(1) spell overlap detection
+- **Armor Set Constraints** - 5+4 logic matches MagSuitBuilder exactly
+- **Coverage Mask** - Body area tracking with reduction logic for multi-slot items
+- **API Endpoints** - `/search`, `/characters`, `/sets` all functional
+- **Streaming Results** - SSE (Server-Sent Events) for real-time feedback
+- **Frontend** - `suitbuilder.html` and `suitbuilder.js` exist and connect to API
+
+### What's Broken
+
+- **Incomplete Bucket Creation** - Only creates 2 buckets (Chest + Head) instead of 11+ slots
+- **Search Exits Early** - Returns first result instead of completing full search
+- **No Item Sorting** - Items processed in database order, not optimal order (best items first)
+- **Goes in Circles** - Previous development sessions made inconsistent changes
+
+### What's Missing
+
+- **AccessorySearcher Phase** - Jewelry optimization not implemented
+- **Item Pre-Filtering** - No "surpassing logic" to remove inferior items before search
+- **Progressive Result Tracking** - Should track top-N suits per piece count
+- **Proper Scoring** - Needs to score by: set completion > spell coverage > armor level
+
+### Code Structure
+
+- `suitbuilder.py`: 1,847 lines
+- Main solver class (`ConstraintSatisfactionSolver`): ~1,130 lines
+
+---
+
+## Section 4: Implementation Plan
+
+**Approach:** Fix incrementally, verify after each step.
+
+Each task is small, self-contained, and testable. Complete one fully before starting the next.
+
+---
+
+### Task 1: Audit & Document Current Search Flow
+
+**Goal:** Understand exactly what the current code does before changing it
+
+**Steps:**
+- Trace through `ConstraintSatisfactionSolver.search()` and document the flow
+- Identify where buckets are created (find the 2-bucket limitation)
+- Identify where search exits early
+- Write findings as comments or separate doc
+
+**Verify:** Can explain the current flow without looking at code
+
+---
+
+### Task 2: Fix Bucket Creation
+
+**Goal:** Create buckets for all 11 armor/clothing slots
+
+**Steps:**
+- Find bucket creation code
+- Add missing slots: Head, Chest, Abdomen, Upper Arms, Lower Arms, Hands, Upper Legs, Lower Legs, Feet, plus clothing slots
+- Ensure items are placed in correct buckets based on `EquipMask`
+
+**Verify:** Log bucket counts - should see items distributed across 11+ buckets, not just 2
+
+---
+
+### Task 3: Fix Search Completion
+
+**Goal:** Search processes ALL buckets before returning results
+
+**Steps:**
+- Find early exit condition
+- Remove or fix it so recursion continues through all buckets
+- Ensure backtracking works correctly
+
+**Verify:** Search logs show "processing bucket 1... bucket 2... bucket 11..." not stopping at 2
+
+---
+
+### Task 4: Add Item Sorting
+
+**Goal:** Process best items first for better pruning
+
+**Steps:**
+- Sort armor items by: set membership → armor level (descending)
+- Sort within each bucket before search begins
+
+**Verify:** Log first 5 items per bucket - should be highest armor level items
+
+---
+
+### Task 5: Implement Proper Scoring
+
+**Goal:** Score suits by correct priority order
+
+**Steps:**
+- Score = (set_completion × 10000) + (spell_coverage × 100) + armor_level
+- Set completion = count of pieces matching primary/secondary sets
+- Update `CompletedSuit` scoring logic
+
+**Verify:** Given two suits, the one with better set completion always scores higher regardless of armor
+
+---
+
+### Task 6: Add Item Pre-Filtering
+
+**Goal:** Remove inferior items before search to reduce search space
+
+**Steps:**
+- Implement "surpassing logic": item A surpasses item B if A has same slot, same set, better stats, and equal/better spells
+- Filter out surpassed items before bucketing
+
+**Verify:** Log shows "Filtered X items down to Y items" with significant reduction
+
+---
+
+### Task 7: Add AccessorySearcher Phase (Future)
+
+**Goal:** After armor search, optimize jewelry slots
+
+**Scope:** Separate task, do after Tasks 1-6 are solid
+
+---
+
+## How to Use This Document
+
+**For Claude (AI assistant):**
+- Read this document at the start of each session
+- Work on ONE task at a time
+- Verify before moving to next task
+- If confused, re-read the relevant section
+- Do NOT make changes outside the current task scope
+
+**For the developer:**
+- Update "Status" at top when tasks complete
+- Add notes under each task as we learn things
+- Reference `magsuitalgo.md` for detailed algorithm explanations
+
+---
+
+## Progress Tracking
+
+| Task | Status | Notes |
+|------|--------|-------|
+| Task 1: Audit Current Flow | Not Started | |
+| Task 2: Fix Bucket Creation | Not Started | |
+| Task 3: Fix Search Completion | Not Started | |
+| Task 4: Add Item Sorting | Not Started | |
+| Task 5: Implement Proper Scoring | Not Started | |
+| Task 6: Add Item Pre-Filtering | Not Started | |
+| Task 7: AccessorySearcher | Not Started | Future |