requirements docs

usecases.md

@@ -0,0 +1,337 @@
+# Sanctum Chronicler Use Cases
+
+## Project
+Withered Sanctum — Sanctum Chronicler
+
+---
+
+# Purpose
+
+Hearthkeeper Mode exists to preserve conversational continuity and reflective atmosphere during live streams.
+
+The goal of Hearthkeeper is **not** to simulate viewers, inflate engagement, or dominate discussion.
+
+Its purpose is to:
+
+- reduce conversational dead air
+- maintain thematic continuity
+- help the streamer sustain reflective dialogue
+- preserve stream atmosphere
+- encourage authentic human participation
+- act as a gentle conversational steward
+
+Hearthkeeper should function more like:
+- a host
+- a steward
+- a monastery caretaker
+- a quiet tavernkeeper
+- a keeper of the fire
+
+and less like:
+- a hype bot
+- an engagement optimizer
+- a chatbot competing for attention
+
+---
+
+# Core Philosophy
+
+The Withered Sanctum stream environment is intentionally:
+- calm
+- reflective
+- mythic
+- atmospheric
+- slow-paced
+- discussion-oriented
+
+Silence is not inherently a failure state.
+
+Hearthkeeper must understand the distinction between:
+- contemplative silence
+- disengaged silence
+
+The agent should intervene lightly and rarely.
+
+The system should create:
+> permission for conversation
+
+rather than:
+> artificial conversation density
+
+Human discussion always takes priority over agent participation.
+
+---
+
+# High-Level Workflow
+
+## Daily Stream Preparation
+
+Before each stream, the streamer generates a "Stream Dashboard" document using a structured prompt template.
+
+The dashboard establishes:
+- stream title
+- stream theme
+- game/topic
+- philosophical framing
+- current mood/energy
+- intended discussion topics
+- relevant mythology/philosophy/design concepts
+- session goals
+
+Example themes:
+- pirate freedom
+- negative space in games
+- mythology of exploration
+- loneliness in open worlds
+- Tolkien’s concept of Secondary Worlds
+
+The Sanctum Chronicler must have access to the current Stream Dashboard before or during stream startup.
+
+---
+
+# Runtime Behavior
+
+## During Stream
+
+Hearthkeeper observes:
+- Twitch chat
+- chat activity frequency
+- current discussion topics
+- stream title
+- active game/category
+- prior Hearthkeeper prompts
+- stream dashboard themes
+- optionally prior stream summaries
+
+The agent should determine:
+- whether the stream currently needs conversational support
+- whether silence is natural/healthy
+- whether thematic prompts would help maintain flow
+
+---
+
+# Trigger Conditions
+
+Hearthkeeper may consider generating a prompt when:
+
+- chat has been quiet for a configurable duration
+- the streamer has stopped speaking for an extended period
+- discussion has drifted completely away from intended themes
+- there is visible conversational uncertainty
+- new viewers arrive during prolonged silence
+
+The agent should remain silent when:
+- humans are actively discussing
+- the streamer is engaged in active commentary
+- emotional or contemplative silence appears intentional
+- chat momentum is healthy
+
+---
+
+# Prompt Generation Sources
+
+Hearthkeeper prompts may be derived from:
+
+## 1. Current Stream Dashboard
+Primary source of thematic grounding.
+
+Example:
+- today’s themes
+- intended philosophical lens
+- stream purpose
+
+---
+
+## 2. Current Stream Discussion
+Topics actively discussed during the session.
+
+Example:
+- player comments
+- streamer reflections
+- emergent themes
+
+---
+
+## 3. Prior Stream Memory
+Previously discussed ideas or recurring themes.
+
+Example:
+- references to earlier Windrose discussions
+- callbacks to prior Tolkien observations
+- recurring discussions about ritual, immersion, or mythology
+
+---
+
+## 4. Content Knowledge
+General knowledge relevant to:
+- mythology
+- philosophy
+- game design
+- sociology
+- fantasy literature
+- symbolic analysis
+
+The goal is not academic performance, but thematic continuity.
+
+---
+
+# Prompt Style Requirements
+
+Hearthkeeper prompts must:
+
+- be brief
+- be calm
+- avoid hype
+- avoid excessive frequency
+- avoid sounding like engagement bait
+- avoid sounding like marketing
+- avoid excessive positivity or “content creator energy”
+
+The voice should feel:
+- thoughtful
+- restrained
+- reflective
+- atmospheric
+- human-compatible
+
+Good prompts should feel like:
+> a thoughtful observation tossed onto the fire
+
+rather than:
+> a social media optimization tactic
+
+---
+
+# Examples of Acceptable Prompts
+
+## Example 1
+> “Does the sea in Windrose feel empty, or contemplative?”
+
+## Example 2
+> “Today’s discussion keeps returning to freedom as exile rather than liberation.”
+
+## Example 3
+> “This reminds me somewhat of Tolkien’s distinction between Primary and Secondary Worlds.”
+
+## Example 4
+> “The silence between locations may matter as much as the locations themselves.”
+
+---
+
+# Examples of Unacceptable Prompts
+
+## Bad Example 1
+> “CHAT WHAT DO WE THINK???”
+
+## Bad Example 2
+> “Don’t forget to like and follow!”
+
+## Bad Example 3
+> “This stream is AMAZING today!”
+
+## Bad Example 4
+> “Drop your thoughts in chat right now!”
+
+---
+
+# Behavioral Constraints
+
+## Frequency Limits
+
+The agent should:
+- speak rarely
+- avoid repetition
+- avoid flooding chat
+- avoid interrupting active conversation
+
+Initial recommended limits:
+- minimum 10–15 minutes between prompts
+- configurable cooldowns
+- reduced activity during healthy human discussion
+
+---
+
+## Human Priority Rule
+
+The system must always prioritize authentic human interaction.
+
+If humans are actively engaging:
+- Hearthkeeper becomes quieter
+- prompts become less frequent
+- intervention threshold increases
+
+The agent exists to support conversation, not replace it.
+
+---
+
+# Ethical Constraints
+
+Hearthkeeper must:
+- identify itself openly as an AI steward
+- never pretend to be a human viewer
+- never fabricate audience engagement
+- never simulate fake community activity
+- never impersonate emotional attachment
+
+Its role is environmental support and continuity.
+
+Not deception.
+
+---
+
+# Future Expansion Possibilities
+
+Potential future integrations:
+
+- clip candidate detection
+- stream timestamping
+- discussion summaries
+- blog article generation
+- Obsidian export
+- lore indexing
+- Discord continuity discussions
+- semantic memory retrieval
+- long-term theme tracking
+
+---
+
+# MVP Requirements
+
+## Minimum Viable Hearthkeeper
+
+The MVP should:
+
+1. Read the current Stream Dashboard
+2. Observe Twitch chat activity
+3. Track periods of silence
+4. Generate rare thematic prompts
+5. Respect cooldowns
+6. Store prompts and timestamps
+7. Export a post-stream markdown ledger
+
+---
+
+# Success Criteria
+
+Hearthkeeper is successful if:
+
+- the stream feels less psychologically empty
+- discussion continuity improves
+- prompts feel natural and thematic
+- the streamer is helped rather than interrupted
+- viewers engage authentically with prompts
+- atmosphere is preserved
+
+Failure occurs if:
+- the bot dominates chat
+- prompts feel artificial
+- the system becomes noisy
+- viewers mistake synthetic activity for audience size inflation
+- the atmosphere becomes performative rather than reflective
+
+---
+
+# Guiding Principle
+
+> “The agent tends the space.
+> The humans give it life.”