update claude.md

CLAUDE.md

@@ -4,7 +4,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a Svelte 5 + TypeScript + Vite single-page application. It uses the latest Svelte 5 with runes syntax (`$state()`, `$derived()`, etc.).
+This is a Svelte 5 + TypeScript + Vite single-page application for a Pokémon-style creature collection game called "Pictuary". It uses the latest Svelte 5 with runes syntax (`$state()`, `$derived()`, etc.).
+
+### Main Features
+- **Monster Generation**: Upload images → AI generates unique creatures ("Piclets") with stats and abilities
+- **Battle System**: Turn-based combat between player and AI opponents  
+- **Collection Management**: Roster of captured Piclets with detailed stats and move sets
+- **Creature Cards**: Trading card-style interface with type-based designs
+- **Image Processing**: AI-powered image captioning and creature concept generation
 
 ## Essential Commands
 
@@ -23,6 +30,12 @@ npm run build
 
 # Preview production build
 npm run preview
+
+# Run tests
+npm test
+
+# Run tests with UI
+npm run test:ui
 ```
 
 ## Architecture
@@ -33,18 +46,79 @@ npm run preview
 - Reusable components go in `src/lib/`
 - Uses Svelte 5 runes syntax (not Svelte 4 syntax)
 
+### Key Components
+- **Pages**: `Scanner.svelte` (main), `Pictuary.svelte` (collection), `Battle.svelte` (combat)
+- **Monster Generation**: `MonsterGenerator.svelte`, `MonsterResult.svelte` (redesigned with PicletCard preview)
+- **Battle System**: `BattleField.svelte`, `ActionButtons.svelte`, turn-based combat logic
+- **Piclet Management**: `PicletCard.svelte`, `PicletDetail.svelte`, `AddToRosterDialog.svelte`
+- **Database**: IndexedDB with `schema.ts` defining PicletInstance, BattleMove, Monster types
+
 ### Key Patterns
 1. **State Management**: Use `$state()` rune for reactive state
 2. **TypeScript**: All components should use `<script lang="ts">` 
 3. **Imports**: Use ES module imports, components are default exports
 4. **Styling**: Component styles are scoped by default, global styles in `src/app.css`
+5. **Database**: IndexedDB operations in `src/lib/db/` with async functions for CRUD operations
 
 ### Build Configuration
 - Vite handles bundling with `vite.config.ts`
 - TypeScript config uses project references (tsconfig.json + tsconfig.app.json)
 - Production builds go to `dist/` directory
 
+## External Dependencies
+
+### Gradio Client Integration
+This project uses Gradio Client for connecting to Hugging Face Spaces. **Important**: Use the CDN-based approach, not npm packages.
+
+**Setup in App.svelte:**
+```javascript
+// CDN imports are loaded dynamically
+import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+window.gradioClient = { Client };
+```
+
+**Usage in other files:**
+```typescript
+// Access via window.gradioClient (types are declared in vite-env.d.ts)
+const client = await window.gradioClient.Client.connect("space-name");
+```
+
+**Current Gradio Connections:**
+- **Flux Image Generation**: `Fraser/flux` 
+- **Joy Caption**: `fancyfeast/joy-caption-pre-alpha`
+- **Zephyr-7B Text Generation**: `Fraser/zephyr-7b` (fallback)
+- **Qwen3 Text Generation**: `Qwen/Qwen3-Demo` (primary)
+
+**Build Notes:**
+- DO NOT install Gradio Client via npm (`npm install @gradio/client`) - it causes build failures
+- The CDN approach ensures compatibility with Vite bundling
+- All Gradio connections should use the established pattern from App.svelte
+
+### Text Generation Architecture
+The project uses a smart fallback system:
+1. **Primary**: Qwen3 via proper Gradio Client connection to `/add_message` endpoint
+2. **Fallback**: Zephyr-7B for when Qwen3 is unavailable
+3. **Manager**: `textGenerationManager` handles automatic switching with connection testing
+
+## Troubleshooting
+
+### Common Build Issues
+- **Gradio Client build failures**: Ensure you're NOT using `npm install @gradio/client`. Use CDN imports only.
+- **Type errors**: Run `npm run check` to identify TypeScript issues before building
+- **Missing dependencies**: Run `npm install` if packages are missing
+
+### Monster Generation Issues  
+- **Name extraction problems**: Check `MonsterGenerator.svelte` line 322 - regex should extract content after `# Monster Name`
+- **Qwen3 connection failures**: System automatically falls back to Zephyr-7B if Qwen3 is unavailable
+- **Image processing errors**: Verify Flux and Joy Caption clients are properly connected
+
+### Performance
+- **Large image files**: Consider image compression before upload
+- **Slow generation**: Qwen3 may take 10-30 seconds for complex monster concepts
+- **Battle lag**: IndexedDB operations are async - ensure proper await usage
+
 ## Important Notes
 - This is NOT SvelteKit - no routing, SSR, or API routes
 - HMR preserves component state (can be toggled in vite.config.ts)
-- All paths in imports should be relative or use `$lib` alias for src/lib
+- All paths in imports should be relative or use `$lib` alias for src/lib
+- IndexedDB is used for local storage - data persists between sessions