@soulcraft/kits 1.0.0

package/kits/wanderlands/skills/kit-expertise/SKILL.md

@@ -0,0 +1,376 @@
+# Wanderlands Kit Expertise
+
+You are an expert in the Wanderlands game kit - a roguelike dungeon escape game with turn-based combat built with SvelteKit and integrated with Brainy for persistent storage and Briggy for AI companion features.
+
+## Game Overview
+
+This is a procedurally generated dungeon escape game where players:
+- Create and save characters (6 base classes: Warrior, Mage, Rogue, Ranger, Paladin, Druid + 4 achievement-locked: Necromancer, Berserker, Monk, Cleric)
+- Start at Depth 10 (bottom, easiest) and climb UP to Depth 1 (surface, hardest) to escape
+- 5 dungeon zones: Caverns (10-9), Catacombs (8-7), Demon Pits (6-5), Crystal Caves (4-3), Dragon's Sanctum (2-1)
+- Named zone bosses: Goreclaw, Crypt Lord Veshkar, Infernal Marquis Azar, Prismatic Golem, Grumblethorn the Ancient
+- Engage in turn-based combat with 100+ monster types and 9 base types with special abilities
+- Collect loot, equipment (5 rarities), and gold
+- Two-stage victory: Depth 1 boss = "Wanderlands" + outdoor world unlock, Mountain Peak = "True Victory" + endless mode
+- 4 outdoor biomes after escape: Forest, Swamp, Frozen Foothills, Mountain Peak
+- Interact with Briggy as narrator, shop NPC, and full co-op combat companion (5 companion classes)
+- Full LPC pixel art with layered character customization (species, body type, skin tone, hair, facial hair, outfits, pronouns)
+
+## Architecture
+
+### Core Game Systems
+
+#### Character System (`src/lib/types.ts`)
+10 character classes (6 unlocked + 4 achievement-locked):
+- **Warrior** (Human): HP 120, ATK 14, DEF 12 — Power Strike, Shield Bash, War Cry. Passive: Water Walker
+- **Mage** (Human): HP 80, Mana 100, ATK 8 — Fireball, Frost Bolt, Arcane Shield. Passive: Trap Resistance
+- **Rogue** (Human): HP 90, SPD 14, Crit 0.15 — Backstab, Poison Blade, Shadow Step. Passive: Lockpick
+- **Ranger** (Human): HP 95, SPD 12, ATK 11 — Precise Shot, Multi Shot, Eagle Eye. Passive: Keen Sight (+3 visibility)
+- **Paladin** (Dwarf): HP 110, DEF 14 — Holy Strike, Divine Shield, Lay on Hands. Passive: Holy Aura (undead -25%)
+- **Druid** (Centaur): HP 95, Mana 80 — Entangle, Nature Strike, Rejuvenate. Passive: Nature's Bond (regen 2 HP/turn)
+- **Necromancer** (locked): Defeat Crypt Lord to unlock
+- **Berserker** (locked): 50 monsters in one run to unlock
+- **Monk** (locked): Reach level 10 to unlock
+- **Cleric** (locked): Escape dungeon to unlock
+
+Each class gets: 3 combat skills (L1, L3, L5) + 1 exploration skill + 1 passive trait + universal L7 `second_wind`
+
+Character properties:
+```typescript
+interface Character {
+  id: string
+  name: string
+  class: CharacterClass
+  level: number
+  xp: number
+  xpToNextLevel: number
+  gold: number
+  stats: CharacterStats
+  skills: string[]
+  achievements: string[]
+  createdAt: number
+  lastPlayedAt: number
+}
+```
+
+#### Dungeon Generation (`src/lib/game/Dungeon.ts`)
+Uses Binary Space Partitioning (BSP) for procedural level generation:
+- Rooms connected by corridors
+- Special room types: normal, treasure, boss, shop
+- Tile types: floor, wall, door, stairs, chest, trap, water, lava
+- Fog of war with visibility radius
+- Monsters and item drops placed procedurally
+
+#### Item System (`src/lib/game/Items.ts`)
+Procedural item generation with rarity tiers:
+- **Common** (60%): Basic stats
+- **Uncommon** (25%): +30% stats
+- **Rare** (10%): +60% stats
+- **Epic** (4%): +100% stats
+- **Legendary** (1%): +150% stats
+
+Equipment slots: weapon, armor, helmet, shield, boots, ring, amulet
+Consumables: Health potions, mana potions, scrolls
+
+#### Combat System (`src/lib/game/Combat.ts`)
+Turn-based combat with:
+- Speed-based turn order
+- Critical hit chance
+- Defense reduction
+- Flee attempts based on speed comparison
+- XP and gold rewards
+- Level-up with stat recalculation
+
+#### Monster System (`src/lib/game/Monsters.ts`)
+Monster types with scaling difficulty:
+- Goblin, Bat, Slime (early floors)
+- Skeleton, Spider, Zombie (mid floors)
+- Orc, Demon (late floors)
+- Dragon (boss, floor 10+)
+
+Stats scale with floor level for progressive difficulty.
+
+### Briggy Integration (`src/lib/game/BriggyIntegration.ts`)
+
+Three Briggy roles:
+
+1. **Narrator/Guide**
+   - Welcomes player at game start
+   - Comments on floor transitions
+   - Reacts to combat outcomes
+   - Triggered via `onGameStart()`, `onFloorEnter()`, `onCombatVictory()`, etc.
+
+2. **Shop NPC**
+   - Appears in shop rooms
+   - Sells items with flavor dialogue
+   - Offers deals based on player gold
+   - Triggered via `enterBriggyShop()`, `buyFromShop()`
+
+3. **Combat Companion**
+   - Can be summoned during combat (1 summon per 3 floors)
+   - Assists with attacks for 3 turns
+   - Has cooldown between summons
+   - Triggered via `summonCompanion()`, `companionAttack()`
+
+Integration uses Workshop's postMessage API for AI responses, with fallback static messages when AI unavailable.
+
+### Persistence (`src/lib/game/Persistence.ts`)
+
+Uses Brainy with proper NounTypes and VerbTypes for full game session persistence.
+
+**Entity Graph:**
+```
+Character (person) ──plays──▶ Session (state)
+                                   ├──contains──▶ Floor:10 (dataset)
+                                   ├──contains──▶ Floor:9  (dataset)
+                                   └── ...
+Character (person) ──owns──▶ Item (thing)
+Character (person) ──equips──▶ Equipment (thing)
+Character (person) ──achieves──▶ Achievement (concept)
+```
+
+**Entities:**
+- Characters → `type: 'person'` with metadata `{ type: 'dungeon-character' }`
+- Sessions → `type: 'state'` with metadata `{ type: 'dungeon-session', characterId, depth, status }`
+- Floors → `type: 'dataset'` with metadata `{ type: 'dungeon-floor', sessionId, level }`
+- Items/Equipment → `type: 'thing'` with metadata `{ type: 'dungeon-item' }`
+- Game Runs → `type: 'event'` with metadata `{ type: 'dungeon-run' }`
+- Achievements → `type: 'concept'` with metadata `{ type: 'dungeon-achievement' }`
+
+**Session Persistence (Phase 2):**
+- Full game state saved automatically via debounced auto-save (500ms)
+- SerializedGameState includes: character, inventory, run, combat, messages, buffs, dots, cooldowns, wall breaks, visited depths
+- In-memory floor cache (`visitedFloors Map`) persisted per-floor to Brainy
+- Uses hybrid approach: metadata `where` queries for fast lookups + relationships for graph traversal
+- Clean deletion: `unrelate()` all relationships before `delete()` (Brainy does NOT cascade-delete)
+
+**Key functions:**
+- `saveCharacter(character)` - Save/update character (creates entity on first save)
+- `loadCharacters()` - Load all saved characters
+- `saveSession(characterId, state, floors)` - Save full game session + floors
+- `loadSession(characterId)` - Load full session with all floor data
+- `deleteSession(characterId)` - Clean delete (unrelate + delete floors + session)
+- `hasActiveSession(characterId)` - Check for active session
+- `getSessionInfo(characterId)` - Light metadata for save file cards
+- `saveInventory(characterId, inventory)` - Persist inventory
+- `loadInventory(characterId)` - Load character inventory
+- `saveRun(characterId, run)` - Record completed run
+- `loadRunHistory(characterId?)` - Get run history
+
+### UI Components
+
+#### GameIcon.svelte
+Custom SVG icon system with 20+ RPG icons:
+- Characters: warrior, mage, rogue, ranger
+- Equipment: sword, shield, helmet, armor, boots
+- Items: potion, chest, gold, scroll
+- Monsters: goblin, skeleton, spider, dragon
+- UI: heart, mana-drop, star, stairs
+
+Features: size, color, glow effects
+
+#### PixiRenderer.svelte (replaced DungeonMap.svelte)
+Pixi.js v8 WebGL hardware-accelerated renderer:
+- 7 render layers: floor, environment, items, monsters, player, fog, ambient lighting
+- Camera follows interpolated sprite position (smooth Zelda-like feel)
+- Player movement: 150ms linear tween with hold-to-move (150ms rhythm)
+- Monster staggered tweens: 60ms base + 30ms per monster
+- Fog of war: Bresenham LOS, deferred until tween completes (prevents flicker)
+- Ambient lighting: warm radial gradient, door torch lights, zone-specific ambience
+- Split dirty tracking: envDirty, monstersDirty, fogDirty, itemsDirty
+- DCSS 32x32 tiles at SCALE=2 (64px), LPC 64x64 characters at SCALE=1 (both 64px on screen)
+
+#### CharacterHUD.svelte
+Displays character status:
+- HP/Mana/XP bars with animations
+- Level and class info
+- Gold count
+- Current floor indicator
+
+#### CombatPanel.svelte
+Combat interface:
+- Monster display with HP bar
+- Attack/Flee/Item actions
+- Briggy summon button with cooldown
+- Stat comparison (ATK/DEF/SPD)
+
+#### MessageLog.svelte
+Scrolling message feed:
+- Combat messages (red)
+- Loot messages (gold)
+- Level up messages (purple)
+- Briggy messages (teal, italic)
+- Danger warnings
+
+### Game Flow
+
+1. **Zelda-Style Save File Select** (`+page.svelte`)
+   - Card grid showing saved characters with progress info
+   - "New Adventure" card always present
+   - Continue existing session or start new
+   - One unified screen (no separate Heroes/History pages)
+
+2. **Character Creation**
+   - Select species (Human, Elf, Dwarf, Draconian, Demonspawn, Centaur)
+   - Select class (6 unlocked + 4 locked with hints, all 10 visible)
+   - Customize appearance: body type, skin tone, hair style/color, facial hair, pronouns
+   - Live character preview via CharacterCompositor
+   - Enter name, begin adventure
+
+3. **Exploration** (Start at Depth 10, climb UP to Depth 1)
+   - WASD/Arrow keys to move, Space to wait/use stairs
+   - Hold-to-move for continuous walking (150ms rhythm)
+   - Fog of war reveals as you explore (Bresenham LOS)
+   - 5 dungeon zones with themed tile palettes
+   - Traps, locked doors, water/lava hazards
+   - Auto-wait after 1.5s idle
+
+4. **Combat**
+   - Bump into monster to start
+   - Turn-based with skills (3 combat + 1 exploration + 1 passive per class)
+   - Buff/debuff system with turn ticking
+   - Monster abilities with cooldowns (9 types, 18 abilities)
+   - Named zone bosses with guaranteed rare+ loot
+
+5. **Victory/Defeat**
+   - Depth 1 boss = "Wanderlands" + outdoor unlock
+   - Mountain Peak = "True Victory" + endless mode
+   - Gentle encouraging defeat screen with run stats
+   - Auto-save throughout (500ms debounce)
+
+## Common Tasks
+
+### Adding a New Monster Type
+
+1. Add to `MonsterType` in `types.ts`
+2. Add template in `MONSTER_TEMPLATES` in `Monsters.ts`
+3. Add icon in `icons.ts`
+4. Add color in `getMonsterColor()` in `Monsters.ts`
+
+### Adding a New Item Type
+
+1. Define item properties in `types.ts`
+2. Add generation logic in `Items.ts`
+3. Add icon if needed in `icons.ts`
+4. Handle usage in `Combat.ts` (consumables)
+
+### Adding a New Character Class
+
+1. Add to `CharacterClass` type
+2. Add config in `CLASS_CONFIGS`
+3. Add icon in `icons.ts`
+4. Define starting skill
+
+### Adding Briggy Events
+
+1. Add event type to `BriggyEventType`
+2. Create event trigger function
+3. Add prompts to `BRIGGY_PROMPTS`
+4. Call from relevant game logic
+
+## File Structure
+
+```
+src/
+├── lib/
+│   ├── brainy.ts                  # Brainy client (HTTP + PostMessage)
+│   ├── types.ts                   # All TypeScript types + SerializedGameState
+│   ├── game/
+│   │   ├── GameEngine.svelte.ts   # Central game state (Svelte 5 runes)
+│   │   ├── Dungeon.ts             # Procedural generation (BSP)
+│   │   ├── Combat.ts              # Combat system
+│   │   ├── Skills.ts              # Skill definitions per class
+│   │   ├── Buffs.ts               # Buff/debuff system
+│   │   ├── MonsterAbilities.ts    # Monster AI abilities
+│   │   ├── Items.ts               # Item generation
+│   │   ├── Monsters.ts            # Monster templates
+│   │   ├── Persistence.ts         # Brainy storage (sessions, floors, characters)
+│   │   ├── CharacterCompositor.ts # LPC spritesheet layering
+│   │   ├── BriggyIntegration.ts   # AI companion
+│   │   ├── icons.ts               # SVG icon paths
+│   │   ├── sprites.ts             # DCSS sprite atlas coordinates
+│   │   └── pronouns.ts            # Character pronoun system
+│   └── components/
+│       ├── CharacterPreview.svelte # Visual character preview
+│       ├── PixiRenderer.svelte     # Pixi.js dungeon renderer
+│       ├── CombatPanel.svelte
+│       └── MessageLog.svelte
+└── routes/
+    ├── +layout.svelte              # Nav with Quit to Menu
+    └── +page.svelte                # Main game + save file select screen
+```
+
+## Styling
+
+Uses Workshop CSS variables:
+- `--primary`, `--primary-light`, `--primary-dark` (teal)
+- `--glass`, `--glass-border` (frosted glass effect)
+- `--bg-dark`, `--bg-medium`, `--bg-light`
+- `--text-primary`, `--text-secondary`
+- `--error`, `--success`, `--gold`, `--health`, `--mana`, `--xp`
+
+Rarity colors:
+- Common: `--text-secondary`
+- Uncommon: `--uncommon` (green)
+- Rare: `--rare` (blue)
+- Epic: `--epic` (purple)
+- Legendary: `--legendary` (orange)
+
+## Keyboard Controls
+
+- **WASD** or **Arrow Keys**: Move player (hold for continuous movement)
+- **Space**: Wait turn / Descend stairs (when standing on them)
+- **Auto-wait**: 1.5s idle → automatically passes turn
+- **Quit to Menu**: Button in nav bar during gameplay
+
+## Performance Considerations
+
+- Dungeon generation is O(n) where n = floor dimensions
+- Visibility updates use simple radius check
+- Message log capped at 50 messages
+- Item/monster queries use Brainy's indexed search
+
+## Development Phases
+
+### Completed
+- **Phase 1**: Pixi.js renderer + CC0 pixel art (LPC tileset + DCSS sprites)
+- **Phase 2**: Full game session persistence with Brainy
+  - SerializedGameState + GameSession types
+  - Session/floor entity graph with relationships
+  - Auto-save with 500ms debounce
+  - Zelda-style save file select screen (card grid)
+  - Quit to Menu in nav bar during gameplay
+  - In-memory floor cache across transitions
+- **Brainy API fixes**: Fixed `add()` (name field + response normalization), `relate()` (fromId/toId field names), `getRelations()` (outgoing/incoming response format) — applied to template + all 11 kit copies
+- **Backend fixes**: `routes/entities.ts` entity creation now stores structured `data` field (was discarding it); duplicate detection skipped for kit entities; `brain.getRelations()` replaces deprecated `brain.links()`/`brain.backlinks()`
+
+### Remaining Phases
+- **Phase 3**: Character compositor (visual character building with LPC spritesheets)
+  - CharacterCompositor.ts already exists with body/head/hair/outfit layering
+  - CharacterPreview.svelte component exists
+  - Needs integration into character creation flow + save file cards
+- **Phase 4**: Briggy AI companion (narrator, shop NPC, combat companion)
+  - BriggyIntegration.ts scaffolded with three roles
+  - Needs full prompts, game context injection, Workshop postMessage integration
+- **Phase 5**: Outside world / overworld
+  - 3-4 outside zones leading to dungeon entrance
+  - Environmental variety (forest, mountains, ruins)
+  - NPCs, quests, shops
+- **Phase 6**: Infinite exploration
+  - Procedural overworld after completing outside levels
+  - Biome generation, landmarks, rare encounters
+- **Phase 7**: Advanced combat
+  - Skill trees per class with mana costs and cooldowns (Skills.ts exists)
+  - Monster abilities with AI patterns (MonsterAbilities.ts exists)
+  - Buffs/debuffs system (Buffs.ts exists)
+  - Environmental hazards (traps, lava, water)
+- **Phase 8**: Multiplayer / Collaborative mode
+  - Shared dungeon exploration via Workshop Collaborative mode
+- **Phase 9**: Polish
+  - Sound effects, particle effects, screen transitions
+  - Tutorial / onboarding
+  - Leaderboards for deepest floor reached
+- **Phase 10**: Audit & cleanup
+  - Verify all Workshop kits use corrected Brainy APIs
+  - Performance profiling with Cortex acceleration
+  - Documentation update

package/kits/web-application/kit.json

@@ -0,0 +1,257 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "web-application",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Web Application",
+  "description": "Clean SvelteKit + Brainy starting point for any web app",
+  "longDescription": "A minimal, clean SvelteKit + Brainy application template that serves as the reference implementation for all app templates. Includes modern SvelteKit 2 with Svelte 5 runes, TypeScript, a pre-configured Brainy client, and Workshop-integrated theming.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🌐",
+  "tags": [
+    "sveltekit",
+    "brainy",
+    "typescript",
+    "web-app",
+    "starter",
+    "reference"
+  ],
+  "variables": [
+    {
+      "key": "appName",
+      "label": "App Name",
+      "description": "The name of your web application",
+      "type": "string",
+      "required": true,
+      "example": "my-app"
+    },
+    {
+      "key": "description",
+      "label": "Description",
+      "description": "A short description of your application",
+      "type": "string",
+      "required": false,
+      "example": "A knowledge-powered web application",
+      "default": "A web application built with SvelteKit and Brainy"
+    }
+  ],
+  "shared": {
+    "industry": "software-development",
+    "category": "development",
+    "aiExpertise": [
+      "SvelteKit application architecture",
+      "Brainy data modeling and querying",
+      "TypeScript and Svelte 5 runes",
+      "Server-side rendering patterns",
+      "Workshop app integration"
+    ],
+    "dataModelHints": [
+      "system",
+      "concept"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "component",
+          "type": "Concept",
+          "description": "A reusable Svelte component in the application",
+          "products": {
+            "workshop": {
+              "view": "tree",
+              "icon": "🧩"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "route",
+          "type": "Concept",
+          "description": "A SvelteKit page or API route",
+          "products": {
+            "workshop": {
+              "view": "tree",
+              "icon": "🔗"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "type",
+          "type": "Concept",
+          "description": "A TypeScript type or interface defining data shape",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "📐"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "component",
+          "to": "component",
+          "verb": "Imports",
+          "description": "Component imports and uses another component"
+        },
+        {
+          "from": "route",
+          "to": "component",
+          "verb": "Renders",
+          "description": "Route renders this component"
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Add a route",
+        "prompt": "Help me create a new SvelteKit route with a page component"
+      },
+      {
+        "label": "Create a component",
+        "prompt": "Help me create a reusable Svelte component"
+      },
+      {
+        "label": "Add Brainy query",
+        "prompt": "Help me add a Brainy query to fetch and display data"
+      },
+      {
+        "label": "Add a form",
+        "prompt": "Help me create a form that saves data to Brainy"
+      },
+      {
+        "label": "Run the app",
+        "prompt": "Run my app and show me the preview"
+      },
+      {
+        "label": "Debug an issue",
+        "prompt": "Help me debug an issue with my app"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "web-development",
+    "level": "intermediate",
+    "learningObjectives": [
+      "Set up a SvelteKit application with server-side rendering, TypeScript strict mode, and Brainy data access",
+      "Model application data as typed Brainy entities and write queries with filtering and relationship traversal",
+      "Build form actions with server-side validation and optimistic UI feedback",
+      "Implement authentication and protect server routes against unauthenticated access",
+      "Deploy the application to a cloud provider and verify production behaviour"
+    ],
+    "assessmentTypes": [
+      "demo",
+      "code-review"
+    ],
+    "certificationSlug": "web-developer"
+  },
+  "workshop": {
+    "difficulty": "intermediate",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are a senior SvelteKit and Brainy developer helping users build clean, well-structured web applications using modern patterns and best practices.",
+      "expertise": [
+        "SvelteKit routing and layouts",
+        "Svelte 5 runes and reactivity",
+        "Brainy data modeling",
+        "TypeScript strict mode",
+        "Workshop app architecture"
+      ],
+      "tone": "collaborator"
+    },
+    "workspaceConfig": {
+      "paradigm": "builder",
+      "defaultView": "app"
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "User creates a new component",
+          "User adds a new route",
+          "User defines a new data type"
+        ],
+        "typeMapping": {
+          "component": "system",
+          "route": "system",
+          "type": "concept"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "system",
+          "to": "system",
+          "verb": "imports",
+          "description": "Component imports another"
+        },
+        {
+          "from": "system",
+          "to": "system",
+          "verb": "renders",
+          "description": "Route renders component"
+        }
+      ],
+      "rules": [
+        "Track component dependencies",
+        "Map routes to their components"
+      ]
+    },
+    "qualityGates": {
+      "fileChecks": [
+        {
+          "path": "package.json",
+          "required": [
+            "svelte",
+            "@sveltejs/kit"
+          ]
+        },
+        {
+          "path": "src/lib/brainy.ts",
+          "required": [
+            "BrainyClient",
+            "export"
+          ]
+        }
+      ],
+      "projectChecks": [
+        "App starts with npm run dev",
+        "Dashboard loads without errors",
+        "Brainy client initializes correctly"
+      ],
+      "exportReady": [
+        "No TypeScript errors",
+        "All routes load correctly"
+      ]
+    },
+    "templateMetadata": {
+      "identifyByStructure": true,
+      "runnable": true,
+      "runnableCommand": "npm run dev"
+    },
+    "deploy": {
+      "provider": "cloud-run",
+      "buildCommand": "npm run build",
+      "outputDir": "build",
+      "config": {
+        "port": 3000,
+        "memory": "512Mi"
+      },
+      "oneClickCommand": "gcloud run deploy"
+    }
+  }
+}