gogobee/gogobee_housing_babysitter.md

GogoBee — Housing & Babysitter Systems

Companion to: gogobee_dnd_design_doc.md, gogobee_expedition_system.md Version: 1.0 Status: Housing — complete spec. Babysitter — design options (decision pending).

---

⚠️ Protected Files — DO NOT MODIFY

All existing *_flavor.go / *_flavor.txt files are off-limits. Housing and babysitter flavor goes in twinbee_housing_flavor.go — new file only.

---

Part One: Housing System

---

1. Overview

Housing gives players a persistent home base — a physical address in the GogoBee world that persists between expeditions, provides mechanical benefits, and represents long-term investment. It is the anchor of the non-expedition economy.

Housing integrates with:

• Long rests (home = free long rest, always available)
• Storage (inventory overflow, rare item safekeeping)
• Crafting (certain recipes require a home workshop)
• Passive income (upgraded properties generate coins over time)
• Expedition prep (supply storage, base camp fast-travel anchor)
• Pet housing (pets need somewhere to live when you're away)
• Babysitter system (see Part Two)
• Thom Krooke (mortgage holder, property broker)

---

2. Property Tiers

Players begin homeless and progress through tiers by purchasing or renting. Each tier unlocks new capabilities.

Tier	Property Type	Acquisition	Base Cost	Long Rest	Storage	Passive Income
0	Homeless	Default	—	Inn only (costs coins)	None	None
1	Rented Room	!rent room	15 coins/week	✅	10 slots	None
2	Rented Apartment	!rent apartment	40 coins/week	✅	25 slots	None
3	Purchased Cottage	!buy cottage	800 coins (mortgage available)	✅	50 slots	5 coins/day
4	Purchased House	!buy house	2,500 coins (mortgage available)	✅	100 slots	15 coins/day
5	Manor	!buy manor	8,000 coins (mortgage available)	✅	250 slots	40 coins/day
6	Estate	!buy estate	25,000 coins (mortgage available)	✅	Unlimited	100 coins/day

2.1 Rent vs. Buy

Renting:

• Weekly payment auto-deducted (Thom Krooke collects)
• No equity, no passive income, no upgrade path
• Miss two consecutive payments → eviction (Tier 0, possessions move to storage for 7 days)
• No mortgage complexity; simple and accessible early game

Buying:

• One-time purchase OR mortgage financing through Thom Krooke (see Section 4)
• Owned property generates passive income
• Upgradeable with rooms, amenities, workshop
• Cannot be repossessed unless mortgage defaults (3 consecutive missed payments)

---

3. Property Upgrades

Owned properties (Tier 3+) can be upgraded with rooms and amenities. Upgrades are permanent and increase property value.

3.1 Upgrade Catalog

Upgrade	Cost	Prerequisite	Benefit
Storage Expansion	200 coins	Any owned	+50 storage slots
Workshop	500 coins	Cottage+	Unlocks home crafting (no Thom Krooke visit required)
Herb Garden	300 coins	Cottage+	Passive: 1d4 common materials/day (zone-agnostic)
Forge	750 coins	House+	Unlocks metal crafting at home; +1 to crafted weapon/armor quality
Library	600 coins	House+	Passive: +1 INT for all INT skill checks while at home
Training Grounds	800 coins	House+	Short rest restores +1d6 additional HP
Guest Room	400 coins	House+	Future: NPC visitors; Babysitter eligible housing (see Part Two)
Vault	1,000 coins	Manor+	Secure storage: items here cannot be lost on death
Trophy Room	500 coins	Manor+	Display legendary items; passive +5% XP gain
Expedition Outpost	1,200 coins	Manor+	Base Camp fast-travel cost reduced; supply storage for active expeditions
Greenhouse	900 coins	Estate	Passive: 1d6 uncommon materials/day (zone-agnostic)
Scriptorium	1,500 coins	Estate	Passive: crafting recipe discovery without !lore checks

3.2 Property Value

Each upgrade adds to the property's assessed value, which affects:

• Passive income calculation (higher value = more income)
• Mortgage refinancing options
• Future resale (sell at 70% of current assessed value)

---

4. Mortgage System

The mortgage system is GogoBee's primary long-term financial mechanic, pegged to real-world ARM rates via the FRED API.

4.1 Mortgage Structure

When a player takes a mortgage via !buy <property> --mortgage:

1. Down payment: 20% of property cost paid upfront
2. Principal: Remaining 80% financed by Thom Krooke
3. Interest rate: Current FRED ARM rate + 2% (Thom Krooke's margin)
4. Term: 30 in-game weeks (real-time weeks)
5. Payment frequency: Weekly, auto-deducted Sunday at reset

Example at current ARM rate (~6.5% + 2% = 8.5%):

Cottage: 800 coins
Down payment: 160 coins
Principal: 640 coins
Weekly payment: ~25 coins/week for 30 weeks
Total paid: ~750 coins (principal + interest)

4.2 ARM Rate Integration

The FRED API is queried weekly (Sunday reset) to fetch the current 5/1 ARM rate.
Rate updates are announced by Thom Krooke via Matrix message to the TwinBee room.

// FREDRateConfig holds the FRED API configuration for ARM rate fetching.
type FREDRateConfig struct {
    SeriesID    string  `json:"series_id"`    // "MORTGAGE5US"
    MarginPct   float32 `json:"margin_pct"`   // Thom Krooke's margin (2.0)
    LastFetched time.Time `json:"last_fetched"`
    CurrentRate float32 `json:"current_rate"` // base rate from FRED
    EffectiveRate float32 `json:"effective_rate"` // base + margin
}

4.3 Mortgage Events

Event	Trigger	Consequence
Rate increase >0.5%	FRED weekly update	Thom Krooke announces; payment adjusts next week
Rate decrease >0.5%	FRED weekly update	Thom Krooke announces; payment adjusts next week
Missed payment	Insufficient coins on Sunday	Warning from Thom Krooke; 10% penalty added
Two missed payments	Second consecutive miss	Thom Krooke visits in person (flavor event); 20% penalty cumulative
Three missed payments	Third consecutive miss	Default: property seized; equity returned at 50%
Early payoff	!mortgage payoff	No penalty; Thom Krooke is genuinely pleased
Refinance	!mortgage refi	Reset term at current rate; available once per 10 weeks

4.4 Thom Krooke Rate Announcements

Thom Krooke posts to the TwinBee Matrix room weekly with the rate update. These are in Thom's voice (Tom Nook parody) and contain the actual FRED rate:

"Good news, friends! The ARM rate this week sits at 7.2% — and with my modest service margin, your mortgage rate is 9.2%. As always, I am here to help. Payments process Sunday. Thank you!"

"The rate has moved up a bit this week — 8.1%, so 10.1% with my fee. Nothing to worry about! Think of it as an investment in your future. Thom Krooke is always here. Always."

4.5 Go Data Model — Mortgage

type Mortgage struct {
    ID              string    `json:"id"`
    PlayerID        string    `json:"player_id"`
    PropertyID      string    `json:"property_id"`
    Principal       int       `json:"principal"`
    Remaining       int       `json:"remaining"`
    DownPayment     int       `json:"down_payment"`
    WeeklyPayment   int       `json:"weekly_payment"`
    InterestRate    float32   `json:"interest_rate"`
    TermWeeks       int       `json:"term_weeks"`
    WeeksRemaining  int       `json:"weeks_remaining"`
    MissedPayments  int       `json:"missed_payments"`
    TotalPaid       int       `json:"total_paid"`
    StartedAt       time.Time `json:"started_at"`
    PaidOffAt       *time.Time `json:"paid_off_at"`
    Defaulted       bool      `json:"defaulted"`
}

---

5. Property State & Commands

5.1 Player Property Record

type PlayerProperty struct {
    PlayerID        string    `json:"player_id"`
    PropertyID      string    `json:"property_id"`
    Tier            int       `json:"tier"`
    Type            string    `json:"type"`        // rented, owned
    Name            string    `json:"name"`        // player-named
    Upgrades        []string  `json:"upgrades"`    // upgrade IDs
    AssessedValue   int       `json:"assessed_value"`
    PassiveIncome   int       `json:"passive_income"` // coins/day
    StorageCapacity int       `json:"storage_capacity"`
    StorageUsed     int       `json:"storage_used"`
    MortgageID      *string   `json:"mortgage_id"`
    AcquiredAt      time.Time `json:"acquired_at"`
    LastRentPaid    *time.Time `json:"last_rent_paid"`
}

5.2 Housing Commands

Command	Description
!home	Summary of current property, upgrades, and status
!home name <name>	Name your property
!rent room / !rent apartment	Rent at current tier
!buy <cottage/house/manor/estate>	Purchase outright
!buy <property> --mortgage	Purchase with Thom Krooke financing
!upgrade <type>	Purchase a property upgrade
!mortgage status	Current mortgage balance, rate, payments remaining
!mortgage payoff	Pay off remaining mortgage balance
!mortgage refi	Refinance at current FRED rate
!storage	View storage inventory
!storage deposit <item>	Store item at home
!storage withdraw <item>	Retrieve item from home storage
!sell property	Sell at 70% assessed value (must own outright)
!passive income	Check daily passive income and last payout

---

6. Housing × Expedition Integration

6.1 Long Rest at Home

Owning or renting any property provides free long rests via !rest long with no inn cost and no cooldown — home is always available.

The Expedition Outpost upgrade extends this: the outpost links to your active Base Camp in a Tier 4–5 zone, allowing one fast-travel per expedition back to base camp from home (and return) without consuming a full travel day.

6.2 Supply Storage

Players with owned properties (Tier 3+) can pre-stage expedition supplies at home:

• !storage deposit supplies <N> — store SU at home
• Supplies stored at home are available for !expedition start without visiting Thom Krooke
• Maximum staged supply = 2× the property's base storage tier
• Herb Garden and Greenhouse upgrades contribute passive SU daily

6.3 Passive Income Collection

Passive income accrues daily at reset. Collected automatically into the player's coin balance. Thom Krooke sends a brief weekly summary:

"Good morning! Your property generated 105 coins this week. Minus your mortgage payment of 25 coins — a net gain of 80. Wonderful, yes?"

---

---

Part Two: Babysitter System — Design Options

---

7. What Is Known

The Babysitter system exists in the GogoBee design. Its purpose is not yet fully defined. The following is known:

• It is a named system — "Babysitter" is intentional, not a placeholder
• It relates to what happens while the player is away (on expedition, offline, or otherwise occupied)
• It likely connects to housing (something to watch over)
• It possibly connects to pets (something to care for)
• It is separate enough from the housing system to warrant its own name

The following are design options — mutually exclusive directions. One should be chosen before implementation begins.

---

8. Design Option A — The Offline Caretaker

Concept: The Babysitter is an NPC hired to manage the player's property and pets while they are on expedition or offline. A literal babysitter for your home.

Mechanics:

• Hired via !hire babysitter at a daily coin cost
• While active, the Babysitter:
  • Feeds and cares for pets (prevents pet happiness decay, if that mechanic exists)
  • Collects passive income from property upgrades (without the Babysitter, income queues but doesn't process)
  • Waters the Herb Garden / Greenhouse (without care, passive material yield halves after 3 days)
  • Accepts deliveries from Thom Krooke (supply orders placed before expedition are ready on return)
• Babysitter has a competence level (1–5) that affects reliability:
  • Level 1: Occasionally forgets things (20% chance of missed task per day)
  • Level 3: Reliable (5% miss chance)
  • Level 5: Perfect (0% miss chance; also occasionally leaves a small gift)
• Babysitter levels up with continued employment (XP from days worked)
• A level 5 Babysitter is a relationship worth maintaining

Cost:

Babysitter Level	Daily Cost
1	3 coins/day
2	6 coins/day
3	10 coins/day
4	15 coins/day
5	22 coins/day

Flavor: The Babysitter is a named NPC (name TBD) with a personality. They leave notes. TwinBee reads the notes aloud on expedition return. The notes are the flavor text.

---

9. Design Option B — The Passive Expedition Support

Concept: The Babysitter is an active support role during expeditions — a companion back at Base Camp or home who provides passive benefits to the expedition in progress.

Mechanics:

• Activated via !babysitter deploy at expedition start (costs coins per day of expedition)
• While deployed, the Babysitter:
  • Reduces supply burn by 10% (they're handling logistics from the rear)
  • Once per expedition, can deliver a supply drop to the player's Base Camp (costs coins + 1 expedition day)
  • Manages the Threat Clock passively (-1 per day via "covering your tracks" at home base)
  • Sends morning intel: +1 to first Perception/Investigation check of each expedition day
• Babysitter cannot enter combat zones — support only
• Deactivates if player is forced to extract (they come to get you)

Cost: 8 coins/day of expedition, prepaid at start.

Flavor: The Babysitter communicates via Matrix messages — brief field reports in the morning, encouraging notes in the evening, occasional observations that are either useful or cryptic depending on TwinBee's mood.

---

10. Design Option C — The Passive Skill Trainer

Concept: The Babysitter is a trainer the player hires to develop skills while they are doing other things — offline training.

Mechanics:

• Hired to train a specific skill or stat for a real-time duration
• While training:
  • The targeted skill/stat gains slow XP passively (cannot exceed 50% of the next threshold via training alone)
  • Training costs coins per hour of real time
  • Player does not need to be online
• Training is interrupted if the player uses the relevant skill in an expedition (expedition XP takes over)
• Maximum one trainer active at a time
• Training has a cap: cannot use training to level up — only to approach the threshold faster

Cost: 2–10 coins/hour depending on stat trained (CHA most expensive; STR cheapest).

Flavor: The trainer has opinions. If you ignore their training by going on expedition, they note it. If you complete a session they trained you for and perform well, they take appropriate credit.

---

11. Design Option D — The Community Role

Concept: The Babysitter is a community-facing role — a player (or designated bot persona) who watches over the TwinBee Matrix room while a player is on expedition, acting as a liaison.

Mechanics:

• One Babysitter role active per expedition (could be another player or an NPC fill-in)
• Babysitter player can:
  • Check on the expedition player's status via !babysit status <player>
  • Send one item or supply cache to an active expedition (costs the Babysitter coins)
  • Vote to activate a community Boost (community milestone modifier to TwinBee mood)
• In return, the Babysitter earns a commission from the expedition's loot (5% of coin value on completion)
• If no player accepts the Babysitter role, an NPC fills it at reduced effectiveness

Flavor: This makes expeditions a community event rather than solo. The Matrix room has a stake in the expedition's outcome. TwinBee acknowledges the Babysitter in morning briefings.

---

12. Design Decision: Option A — The Offline Caretaker

Selected. The Babysitter is an NPC hired to manage the player's property and pets while they are on expedition or offline.

---

13. Babysitter NPC — Pastel

Name: Pastel Source: Recurring support character from the TwinBee series (Konami). In the games, Pastel is the capable, warm-hearted civilian presence while the TwinBee ships are out fighting. In GogoBee, she's the person keeping everything together while you're in the dungeon.

Personality: Warm, slightly tired, completely reliable. Pastel has seen players return from bad expeditions and good ones and treats both the same — with a note on the table and everything in order. She is not impressed by legendary loot. She is genuinely pleased when the pets are happy. She does not complain. She notices everything.

Voice: Domestic, understated, occasionally dry. Contrasts directly with Thom Krooke's relentless salesmanship and TwinBee's dramatic narration. Pastel's register is: this is what I did today, everything is fine, the cat knocked something over.

Level progression:

• Level 1: Enthusiastic but scattered. Means well. 20% chance of missed task per day.
• Level 2: Getting the hang of it. 12% miss chance. Notes are more organized.
• Level 3: Found her rhythm. 5% miss chance. Reliable, efficient, minimal fuss.
• Level 4: Anticipatory. 1% miss chance. Occasionally handles things before they become problems.
• Level 5: Perfect. 0% miss chance. Sometimes leaves a small gift. The right gift.

type BabysitterNPC struct {
    ID          string    `json:"id"`
    Name        string    `json:"name"`       // "Pastel"
    Level       int       `json:"level"`      // 1–5
    FlavorRef   string    `json:"flavor_ref"` // "pastel"
    HiredByID   string    `json:"hired_by_id"`
    HiredAt     time.Time `json:"hired_at"`
    DailyRate   int       `json:"daily_rate"`
    DaysWorked  int       `json:"days_worked"`
    XP          int       `json:"xp"`         // levels up with days worked
    MissChance  float32   `json:"miss_chance"` // 0.20→0.12→0.05→0.01→0.00
}

---

14. Implementation Phases — Housing

Phase H1 — Core Housing

• PlayerProperty struct and DB schema
• Tier 0–2 (homeless, rented room, rented apartment)
• Rent payment auto-deduction (weekly)
• Eviction system
• !home, !rent commands
• Free long rest at rented/owned property

Phase H2 — Ownership & Mortgage

• Tier 3–6 (cottage through estate)
• Mortgage struct and DB schema
• FRED API ARM rate integration (weekly fetch)
• !buy, !mortgage status, !mortgage payoff, !mortgage refi commands
• Thom Krooke rate announcement posts
• Missed payment and default handling

Phase H3 — Upgrades & Passive Systems

• Upgrade catalog implementation
• Passive income daily accrual
• Storage system (!storage commands)
• Herb Garden / Greenhouse passive material yield
• Workshop and Forge crafting unlock

Phase H4 — Expedition Integration

• Supply staging at home
• Expedition Outpost fast-travel link
• Vault (death-proof storage)
• Trophy Room XP bonus

Phase H5 — Babysitter (post-design decision)

• Implement chosen option
• Babysitter NPC creation (name, personality, flavor text)
• twinbee_housing_flavor.go population

---

End of Housing & Babysitter Document. Babysitter direction requires human decision before Phase H5 implementation. Reference alongside all companion docs in Claude Code sessions.