// Package persona provides species-agnostic character description primitives.
//
// This package defines canonical DNA types for character generation systems,
// supporting both humans and humanoids with biological DNA, psychology, and
// validation logic.
//
// # Architecture
//
// The package is organized into several layers:
//
//   - Core Types: Character, DNA, IdentityDNA, FaceDNA, BodyDNA, VoiceDNA
//   - Species System: Human, Humanoid, Android with MorphLevel progression
//   - Psychology: HEXACOProfile, AttachmentStyle, Values
//   - Validation: Species-aware plausibility and consistency checks
//   - Pools: YAML-loaded description pools for prose generation
//
// # Usage
//
//	character := &persona.Character{
//	    ID:      "char_001",
//	    Species: persona.SpeciesHuman,
//	    DNA: &persona.DNA{
//	        Identity: persona.IdentityDNA{
//	            Ethnicity: persona.EthnicityEastAsian,
//	            Age:       28,
//	            Gender:    persona.GenderWoman,
//	        },
//	        Face: persona.FaceDNA{
//	            FaceShape: persona.FaceShapeOval,
//	            EyeShape:  persona.EyeShapeAlmond,
//	            // ...
//	        },
//	    },
//	}
//
//	// Validate the character
//	if err := persona.Validate(character); err != nil {
//	    log.Printf("validation failed: %v", err)
//	}
//
// # Species System
//
// The Species field determines which validation rules apply:
//
//   - Human: Ethnicity plausibility checks (eye color, hair, skin tone)
//   - Humanoid: Morphology validation (ears, tail, fangs require MorphLevel >= 25)
//   - Android: Minimal validation (synthetic beings)
//
// # MorphLevel
//
// For humanoid characters, MorphLevel (0-100) controls transformation intensity:
//
//   - 0-24:  Human appearance with supernatural energy
//   - 25-49: Subtle features (pointed ears, fangs)
//   - 50-74: Demi-human (anime-style ears/tail)
//   - 75-99: Hybrid (fur patterns, scales)
//   - 100:   Full creature form
//
// # Design Principles
//
//   - Category enums (not strings) for type safety
//   - Separate struct for each DNA domain
//   - All fields have json/yaml tags for serialization
//   - Validation is opt-in per species
//   - Pools are YAML-loaded at init() for flexibility
package persona