Kaernest Character Builder - Project Analysis¶

Current Status: STRONG FOUNDATION ✅¶

You have a well-structured React + TypeScript + Vite project with solid architecture. Most of the groundwork is done!

What's Working ✅¶

Data Layer (Complete)¶

Species System: 7 species with elemental themes (Dazhdvog, Fluvarri, Human, Kampanni, Qnassi, Sektarri, Verdanni)
Backgrounds System: Comprehensive list with attribute bonuses, skills, equipment profiles
Skills System: 18+ skills with ranking (novice → apprentice → journeyman → expert → master)
Gifts System: 50+ gifts with CC costs and prerequisites
Equipment System: Weapons, armor, shields, gear with stats
Motivation System: Foundations and ambitions with prompts
JSON Schemas: Validation schemas for all data types

State Management (Complete)¶

Zustand-based character store
Clean action API for all mutations
Character draft type with proper TypeScript
Creation Points (CC) tracking and spending
Equipment state management
Motivation CRUD operations

UI Components (Mostly Complete)¶

Layout system: Clean two-column layout
Species Picker: Working component
Background Picker: Working with attribute/skill selection
Skills Panel: Background skills + extra trained skills
Gifts Panel: Filterable gift selection with CC costs
Equipment Panel: Weapon/armor/shield selection (313 lines - most complex)
Motivations Panel: Add/edit/remove motivations with prompts
Step Navigation: Tab system for creation flow

Creation Flow Steps¶

✅ Basics - Identity (name, role, birth month, player, intent) + Species + Background
❓ Attributes - Referenced in steps.ts but NOT implemented in App.tsx
✅ Skills - Novice skill selection + extra trained skills (CC cost)
✅ Gifts - Gift selection with filtering (CC cost)
✅ Motivations - Foundation/ambition creation
❌ Novice Bump - Placeholder only (needs implementation)
✅ Equipment - Weapon/armor/shield selection
❓ Relationships - Referenced in steps.ts but NOT implemented
❌ Review - Placeholder only (needs implementation)

What's Missing / Incomplete ❌¶

1. Attributes Step (CRITICAL - Currently Skipped!)¶

Problem: The "attributes" step exists in the flow but has no UI in App.tsx What's needed: - UI to display base attributes (from species/background) - Apply attribute bonuses from background - Display final attribute values - Maybe allow spending CC on attribute increases?

2. Novice → Apprentice Bump¶

Current: Just a placeholder card What's needed: - Select ONE novice skill to promote to apprentice rank - Update the character store with the selection - Validation to ensure they have at least one novice skill

3. Relationships Step¶

Current: Missing entirely from App.tsx What's needed: - Define what "relationships" means in your system - UI to add/manage character relationships - Store in character draft

4. Review/Export Step¶

Current: Just a placeholder What's needed: - Complete character sheet view - Print-friendly layout - JSON export/import functionality - PDF generation? - Character validation (all required fields filled)

5. Attribute Calculation System¶

Problem: Background grants attributeBonus but nowhere applies it What's needed: - Calculate base attributes (species bonuses?) - Apply background attribute bonus - Display computed attributes in summary - Rules for attribute caps/limits

Code Quality Observations¶

Strengths 💪¶

Clean separation of concerns: data/, features/, state/, ui/
Type safety: Comprehensive TypeScript types
Reusable components: Pill, Layout, etc.
Consistent patterns: All pickers follow similar structure
Good data modeling: JSON schemas for validation
Python linting tools: For data validation

Areas for Improvement 🔧¶

Missing TypeScript definitions for some data structures
No error boundaries for component failures
No loading states for data fetching
Hard-coded step logic in App.tsx (could be more data-driven)
No persistence (localStorage/sessionStorage)
No undo/redo functionality
Limited accessibility (keyboard nav, ARIA labels)

Immediate Next Steps (Priority Order)¶

Phase 1: Complete Core Flow (Essential)¶

Implement Attributes Step (1-2 hours) - Show base attributes - Apply background bonuses - Handle fixed vs choice bonuses
Implement Novice Bump Step (30 min) - Select skill to bump to apprentice - Store in character draft
Basic Review Step (1 hour) - Summary view of all selections - Export to JSON button

Phase 2: Polish & Features (Nice to Have)¶

Add Character Validation (30 min) - Required fields check - Step completion indicators
Implement Persistence (1 hour) - Save/load from localStorage - Multiple character slots
Define Relationships Step (depends on design) - What are relationships in Kaernest? - NPCs, factions, bonds?

Phase 3: Advanced Features¶

PDF Export (2-3 hours) - Character sheet template - Print-optimized layout
Character Import (1 hour) - Load from JSON file - Validate against schemas

Technical Debt / Issues¶

Known Issues¶

npm install fails - Some global npm config issue (not critical for development)
Attributes not calculated - Background bonus not applied anywhere
Step flow inconsistency - "attributes" step defined but skipped in UI
No loading/error states - Data fetching has basic error handling but no UI feedback

Recommendations¶

Add a CharacterValidator utility to check draft completeness
Create a useAttributes hook to calculate final attribute values
Add localStorage persistence so users don't lose work
Create a CharacterSheet component for the review step
Add unit tests for critical business logic (CC spending, skill selection limits)

Questions to Clarify¶

Attributes: How do species affect base attributes? (I see species have "element" but no explicit stat bonuses in the data)
Relationships: What should this step include? Bonds to other PCs? Faction loyalties?
Novice Bump: Is this just a one-time promotion, or can players do this multiple times?
Character Levels: Does advancement beyond character creation happen in this tool?
Background Evolution: I see backgroundEvolutionSchema.json with journeyman/expert/master options - is this for play or character creation?

Summary¶

You're about 85% done with the character creation flow!

The core architecture is solid, the data layer is excellent, and most UI components work. You're mainly missing: 1. The attributes calculation/display logic 2. The novice bump UI 3. A proper review/export step

With a few focused work sessions, this can be a fully functional character builder. The hardest parts (data modeling, state management, complex UI like equipment) are already done.

Your sister was right - this is very workable code! 🎉