storybook/examples/baker-family/README.md

# Baker Family Example

A comprehensive example demonstrating Storybook v0.3.0 features through a realistic multi-character scenario with relationships, locations, institutions, and advanced type system usage.

## Characters

| Character | Age | Role | Template |
|-----------|-----|------|----------|
| Martha | 34 | Master baker, business co-owner | Baker |
| Jane | 36 | Pastry chef, Martha's wife, co-owner | Baker |
| Emma | 12 | Their daughter, science enthusiast | Child |
| Henry | 68 | Retired teacher, loyal customer | Person |
| Roland | 42 | Competing baker from next town | Baker |

Martha and Jane are a married couple who co-run the bakery. Emma is their daughter. Henry and Roland are community members connected to the family through the bakery.

## Features Demonstrated

### Type System (v0.3.0)
- **Species definitions**: `species Human { ... }` provides default fields for all human characters
- **Species-based templates**: `template Person: Human { ... }` inherits species fields as base layer
- **Concepts and sub-concepts**: `concept BakedGood` with `sub_concept BakedGood.Category { Bread, Pastry, Cake }`
- **Sub-concept dot notation**: Parent.Name format for clear ownership
- **Concept comparisons**: `SkillLevel` maps skill tiers to quality expectations
- **Life arc requirements**: `life_arc BakerCareer requires { baking_skill: Number }` for compile-time validation

### Relationships
- **Marriage**: Martha and Jane, a lesbian couple with asymmetric bakery roles
- **Parent-Child**: Martha-Emma and Jane-Emma with different parenting styles
- **Business Partnership**: Martha and Jane co-owning and co-running the bakery
- **Customer Relationship**: Martha and Henry (daily loyalty)
- **Competition**: Martha and Roland (rival bakers)
- **Asymmetric perspectives**: Each participant has role-specific fields

### Locations
- **MarthasBakery**: Detailed shop with prose description, capacity, hours
- **MainStreet**: Town thoroughfare connecting market and school

### Institutions
- **BakersGuild**: Trade guild with membership, meetings, and governance

### Life Arcs
- **BakerCareer**: Apprentice -> Journeyman -> Master (skill-based progression)
- **Childhood**: Young child -> School age -> Teenager -> Adult (age-based)
- **MarriageQuality**: Newlywed -> Established -> Deep bond (relationship arc)
- **BusinessGrowth**: Starting out -> Growing -> Thriving (business arc)

### Resource Linking
- **Templates with behaviors**: `Baker` template specifies `BakingSkills` and `CustomerService`
- **Templates with schedules**: `Baker` template uses `BakerSchedule`
- **Multi-level inheritance**: `Baker` -> `Worker` -> `Person` template chain
- **Character inheritance**: Characters automatically inherit behaviors and schedules from templates

### Schedule Composition
- **Schedule inheritance**: `BakerSchedule modifies WorkWeek`
- **Override blocks**: Modify inherited time blocks with `override work { ... }`
- **Named blocks**: All blocks have names for the override system
- **Action references**: Schedule blocks reference behavior trees via `action: BehaviorName`
- **Recurrence patterns**: Market day repeats `on Saturday`

### Behavior Trees
- Comprehensive behavior definitions for all activities
- Referenced from schedule blocks showing integration
- Hierarchical behaviors (sequences, selectors, repeaters)

## File Structure

```
baker-family/
├── README.md
├── schema/
│   ├── templates.sb              # Template definitions with species base
│   ├── types.sb                  # Concepts, sub-concepts, species, concept comparisons
│   └── life_arcs.sb              # Career and childhood life arcs
├── characters/
│   ├── martha.sb                 # Master baker (Baker template, skill_tier: Master)
│   ├── jane.sb                   # Pastry chef (Baker template, skill_tier: Journeyman)
│   ├── emma.sb                   # Daughter (Child template)
│   ├── henry.sb                  # Retired teacher customer (Person template)
│   └── roland.sb                 # Competing baker (Baker template)
├── relationships/
│   └── baker_family_relationships.sb  # All relationships with asymmetric perspectives
├── locations/
│   └── bakery_locations.sb       # MarthasBakery and MainStreet
├── institutions/
│   └── bakers_guild.sb           # Trade guild
├── life_arcs/
│   └── family_life_arcs.sb       # MarriageQuality and BusinessGrowth arcs
├── schedules/
│   └── work_schedules.sb         # Composable schedules
└── behaviors/
    └── baker_behaviors.sb        # Behavior tree definitions
```

## Template Hierarchy

```
Human (species - default fields: age, energy, mood, occupation)
  └─> Person: Human (behaviors: BasicNeeds, SocialInteraction)
       ├─> Worker (schedule: WorkWeek)
       │    └─> Baker (behaviors: +BakingSkills, +CustomerService, schedule: BakerSchedule)
       │         ├── Martha (skill_tier: Master)
       │         ├── Jane (skill_tier: Journeyman)
       │         └── Roland (skill_tier: Journeyman)
       │
       └─> Child: Human (behaviors: PlayBehavior, LearnBehavior, no schedule)
            └── Emma

  └─> Henry (Person, retired, no work schedule)
```

Override chain: Species -> Includes -> Template -> Character (last-one-wins)

## Relationship Map

```
Martha ──── Marriage ──── Jane
  │    BusinessPartnership   │
  │                          │
  ├── ParentChild ── Emma ───┘
  │
  ├── CustomerRelationship ── Henry
  │
  └── Competition ── Roland
```

## Schedule Inheritance

```
WorkWeek
  ├─ morning_prep (08:00-09:00)
  ├─ work (09:00-17:00)
  └─ evening_rest (18:00-22:00)

BakerSchedule modifies WorkWeek
  ├─ pre_dawn_prep (04:00-05:00) [NEW]
  ├─ work (05:00-13:00) [OVERRIDE] -> action: BakingWork
  ├─ evening_rest (18:00-22:00) [INHERITED]
  └─ recurrence MarketDay on Saturday
       └─ market (06:00-14:00) -> action: SellAtMarket
```

## Life Arcs

```
BakerCareer requires { baking_skill: Number, work_ethic: Number }
  apprentice -> journeyman (when baking_skill > 0.5 and work_ethic > 0.7)
  journeyman -> master (when baking_skill > 0.8 and work_ethic > 0.9)

Childhood requires { age: Number, curiosity: Number }
  young_child -> school_age -> teenager -> adult

MarriageQuality requires { relationship_quality: Number, years_together: Number }
  newlywed -> established -> deep_bond

BusinessGrowth requires { customer_relations: Number, baking_skill: Number }
  starting_out -> growing -> thriving
```

## Concept Comparison: SkillLevel

Maps baking skill tiers to quality expectations:
- **Apprentice**: Any freshness level acceptable while learning
- **Journeyman**: Any freshness level expected as standard
- **Master**: Must produce fresh goods to meet the standard

## Key Integration Points

1. **Martha (character)** -> inherits from **Baker (template)** -> inherits from **Human (species)**
   - Gets default fields from Human species (age, energy, mood, occupation)
   - Gets behaviors: `BakingSkills`, `CustomerService`, `BasicNeeds`, `SocialInteraction`
   - Gets schedule: `BakerSchedule` (which modifies `WorkWeek`)
   - Has `skill_tier: Master` for concept comparison mapping

2. **Relationships** -> connect characters with asymmetric perspectives
   - Martha and Jane's Marriage and BusinessPartnership show the same couple in different roles
   - Each participant has role-specific fields
   - Competition relationship shows non-familial connections

3. **Locations** -> provide narrative context with prose descriptions
   - `MarthasBakery` is referenced by schedules and behaviors
   - `MainStreet` connects the bakery to the wider community

4. **Life arcs** -> track progression across multiple dimensions
   - Career (BakerCareer), personal growth (Childhood)
   - Relationship quality (MarriageQuality), business success (BusinessGrowth)

## Usage

This example shows how to:
- Define species with default fields for character archetypes
- Build reusable templates with species inheritance
- Use concepts and sub-concepts for type-safe enumerations
- Create concept comparisons for compile-time pattern matching
- Define life arcs with field requirements for validation
- Model relationships with asymmetric participant perspectives
- Create locations and institutions with prose descriptions
- Compose schedules through inheritance and overrides
- Link schedules to behaviors through action references
- Model realistic daily routines with time-of-day variations