release: Storybook v0.2.0 - Major syntax and features update

BREAKING CHANGES: - Relationship syntax now requires blocks for all participants - Removed self/other perspective blocks from relationships - Replaced 'guard' keyword with 'if' for behavior tree decorators Language Features: - Add tree-sitter grammar with improved if/condition disambiguation - Add comprehensive tutorial and reference documentation - Add SBIR v0.2.0 binary format specification - Add resource linking system for behaviors and schedules - Add year-long schedule patterns (day, season, recurrence) - Add behavior tree enhancements (named nodes, decorators) Documentation: - Complete tutorial series (9 chapters) with baker family examples - Complete reference documentation for all language features - SBIR v0.2.0 specification with binary format details - Added locations and institutions documentation Examples: - Convert all examples to baker family scenario - Add comprehensive working examples Tooling: - Zed extension with LSP integration - Tree-sitter grammar for syntax highlighting - Build scripts and development tools Version Updates: - Main package: 0.1.0 → 0.2.0 - Tree-sitter grammar: 0.1.0 → 0.2.0 - Zed extension: 0.1.0 → 0.2.0 - Storybook editor: 0.1.0 → 0.2.0
2026-02-13 21:52:03 +00:00
parent 80332971b8
commit 16deb5d237
290 changed files with 90316 additions and 5827 deletions
--- a/docs/tutorial/06-relationships.md
+++ b/docs/tutorial/06-relationships.md
@@ -0,0 +1,212 @@
+# Character Relationships
+
+Characters exist in a web of connections -- friendships, rivalries, parent-child bonds, and complex power dynamics. In Storybook, relationships are first-class declarations that capture these connections with nuance and perspective.
+
+## Basic Relationships
+
+The simplest relationship connects two characters with shared fields:
+
+```storybook
+relationship MarthaAndEmma {
+    Martha as parent {}
+    Emma as child {}
+
+    bond: 0.95
+    type: "parent_child"
+}
+```
+
+This says Martha and Emma share a relationship with a bond strength of 0.95 (very close). The `bond` field is shared -- it applies equally to both participants.
+
+## Adding Roles
+
+Roles label each participant's function in the relationship:
+
+```storybook
+relationship ParentChild {
+    Martha as parent
+    Emma as child
+
+    bond: 0.95
+    guardianship: true
+}
+```
+
+The `as parent` and `as child` labels clarify who plays which role. Roles are descriptive -- you can use any name that makes sense.
+
+## Perspectives: Self and Other
+
+Real relationships are not symmetric. How one person sees the relationship may differ from how the other sees it. Storybook handles this with `self` and `other` blocks:
+
+```storybook
+relationship MentorApprentice {
+    Martha as mentor self {
+        patience: 0.8
+        investment_in_student: 0.9
+    } other {
+        sees_potential: 0.85
+        frustration_level: 0.2
+    }
+
+    Elena as apprentice self {
+        dedication: 0.9
+        overwhelmed: 0.4
+    } other {
+        admiration: 0.95
+        desire_to_impress: 0.9
+    }
+
+    bond: 0.85
+}
+```
+
+Reading this:
+- **Martha's self view**: She feels patient (80%), highly invested in her student
+- **Martha's view of Elena (other)**: Sees high potential (85%) with low frustration (20%)
+- **Elena's self view**: Dedicated (90%) but sometimes overwhelmed (40%)
+- **Elena's view of Martha (other)**: Deep admiration (95%), strong desire to impress (90%)
+- **Shared**: Their bond strength is 0.85
+
+## Prose in Relationships
+
+Relationships can include narrative descriptions for each participant:
+
+```storybook
+relationship MarthaAndGregory {
+    Martha {
+        role: shopkeeper
+        values_loyalty: 0.9
+
+        ---perspective
+        Martha appreciates Gregory's unwavering loyalty. He has
+        been buying her sourdough loaf every morning for fifteen
+        years. Their brief daily exchanges about the weather and
+        local gossip are a comforting routine.
+        ---
+    }
+
+    Gregory {
+        role: regular_customer
+        always_orders: "sourdough_loaf"
+
+        ---perspective
+        Gregory considers Martha's bakery a cornerstone of his
+        daily routine. The bread is excellent, but it is the brief
+        human connection that keeps him coming back. He worries
+        about what would happen if she ever retired.
+        ---
+    }
+
+    bond: 0.7
+}
+```
+
+## Multi-Party Relationships
+
+Relationships can involve more than two participants:
+
+```storybook
+relationship BakerFamily {
+    Martha as parent
+    Jane as parent
+    Emma as child
+
+    household: "Baker Residence"
+    family_bond: 0.95
+    dinner_time: 18:00
+
+    ---dynamics
+    A loving family running a bakery together. Martha handles
+    the bread, Jane manages pastries, and Emma helps out on
+    weekends while learning the craft.
+    ---
+}
+```
+
+## Asymmetric Awareness
+
+Relationships can model situations where one party does not know the relationship exists:
+
+```storybook
+relationship BossAndNewHire {
+    Martha {
+        role: boss
+        aware_of_struggles: false
+        expects: high_quality_work
+
+        ---perspective
+        Martha sees the new hire as competent and expects them
+        to learn the bakery routines quickly. She has no idea
+        they are struggling with the early morning schedule.
+        ---
+    }
+
+    NewHire {
+        role: employee
+        intimidated: 0.8
+        hides_struggles: true
+
+        ---perspective
+        The new hire is in awe of Martha's skill but terrified
+        of disappointing her. They arrive thirty minutes early
+        every day to practice techniques before she gets in.
+        ---
+    }
+
+    bond: 0.4
+}
+```
+
+## Institutional Relationships
+
+Institutions can participate in relationships too:
+
+```storybook
+relationship GuildMembership {
+    Martha as member
+    BakersGuild as organization
+
+    membership_since: "2015-01-01"
+    standing: "good"
+    dues_paid: true
+}
+```
+
+## Building a Relationship Web
+
+Multiple relationships create a rich social network:
+
+```storybook
+relationship Marriage {
+    Martha as spouse
+    Jane as spouse
+    bond: 0.9
+}
+
+relationship MentorApprentice {
+    Martha as mentor
+    Elena as apprentice
+    bond: 0.85
+}
+
+relationship RegularCustomer {
+    Martha as shopkeeper
+    Gregory as customer
+    bond: 0.7
+}
+
+relationship Colleagues {
+    Martha as peer
+    NeighborBaker as peer
+    bond: 0.5
+    competitive: true
+}
+```
+
+## Next Steps
+
+Characters have traits, behaviors, and relationships. In [Schedules and Time](./07-schedules.md), you will give them daily routines and time-based activities.
+
+---
+
+**Reference**: For complete relationship syntax, see the [Relationships Reference](../reference/15-relationships.md).