session-log

# Session Log > **Human-readable markdown logs that tell stories.** Session logs are **living documents** that capture the narrative of play. Unlike technical event logs, sessions are meant to be READ — by users, by future LLMs warming context, by anyone who wants to understand what happened. > [!IMPORTANT] > Session logs are **NOT append-only!** They are living documents that grow and improve over time. You can and should retroactively improve them as new information comes in. --- ## 📍 Where Sessions Live The default session file is **`SESSION.md`** in the character directory: ``` characters/ ├── real-people/don-hopkins/ │ ├── CHARACTER.yml │ └── SESSION.md ← Default session log ├── fictional/donna-toadstool/ │ ├── CHARACTER.yml │ └── SESSION.md ← Default session log └── animals/monkey-palm/ ├── CHARACTER.yml └── SESSION.md ← Default session log ``` ### Naming Sessions You can create multiple session files with descriptive suffixes: | Session File | Purpose | |--------------|---------| | `SESSION.md` | Default — the main session log | | `SESSION-day1-exploration.md` | Specific day or theme | | `SESSION-fluxx-marathon.md` | Named adventure arc | | `SESSION-debug-investigation.md` | Debugging session | **Command:** `START SESSION [name]` — Creates a new session file with optional suffix. --- ## 📝 Writing Good Sessions ### The Golden Rule **Sessions are meant to be read by humans.** Write them like stories, not logs. ### Structure with Outlines Use `<details open>` tags to create **collapsible sections** that: - Show narrative meant to be read (opened) - Hide technical data and debugging (closed) - Group related content into logical sections - Allow readers to drill down on demand ```markdown <details open> <summary><h2>🌟 Chapter Title — Descriptive Subtitle</h2></summary> The narrative content goes here. This is what readers see first. <details open> <summary>📂 <strong>Technical details: What the YAML changes looked like</strong></summary> ```yaml # The YAML data island state_change: file: ./CHARACTER.yml changes: [location, inventory] ``` </details> </details> ``` ### Outline Patterns | Pattern | When to Use | State | |---------|-------------|-------| | `<details open>` | Narrative chapters — always show | **Open** | | `<details open>` | Technical details — hide by default | **Closed** | | Nested `<details open>` | Data within narrative | Mixed | ### The Summary Line The `<summary>` is part of the narrative! Write it as a headline: ```markdown <!-- BAD: Generic summaries --> <summary>Turn 5</summary> <summary>File operations</summary> <!-- GOOD: Descriptive headlines --> <summary><h2>🌟 Turn 5: The Wish is Spoken — Palm's Incarnation</h2></summary> <summary>📂 <strong>File creation: CHARACTER.yml with 32 Mind Mirror dimensions</strong></summary> ``` ### Use Emojis in Section Headers Add emojis **after the folder icon** for narrative sections: | Emoji | Meaning | |-------|---------| | 📂 | Technical/collapsed section | | 🌟 | Major milestone | | 🎭 | Character transformation | | 🗺️ | Exploration/travel | | 💬 | Dialogue/conversation | | 🎰 | Games/randomness | | 🐕 🐱 🐵 | Animal character sections | | ⚡ | Speed-of-light simulation | --- ## 📊 Session Index **Keep an index at the top of every session!** Update it retroactively as you append. ```markdown <details open> <summary><h2>⭐ Session Highlights & Index</h2></summary> ### 📚 Session Index (Internal Links) **Day 1 — The Wish** - [🌿 LOOK AROUND](#-look-around) — First impressions - [Turn 1: Talk to Marieke](#turn-1-talk-to-marieke) — Lucky strains - [Turn 7: THE WISH IS SPOKEN](#turn-7-the-wish-is-spoken-) — 🌟 Palm's incarnation **Day 2 — The Fluxx Marathon** - [🎰 33 Turns of Gezelligheid](#33-turns-of-gezelligheid) — Speed of Light demo ### 🏠 Key Locations (External Links) | Location | Description | |----------|-------------| | [Palm's Nook](../../examples/adventure-4/pub/stage/palm-nook/) | The monkey's home | | [The Pub](../../examples/adventure-4/pub/) | Main location | </details> ``` ### Index Rules 1. **Internal links** use anchor syntax: `[Title](#anchor-name)` 2. **External links** use relative paths: [`File`](../../examples/adventure-4/pub/pie-table.yml) 3. **Update retroactively** — every append is a chance to improve the index 4. **Group by day/arc** — natural narrative divisions --- ## 🔗 Linking Generously **Links draw people into the repo!** Every file, character, room, and skill mentioned should be a link. ### Link Everything ```markdown <!-- BAD: No links --> Palm wrote an essay about being a monkey. <!-- GOOD: Link everything --> [Palm](../../examples/adventure-4/characters/animals/monkey-palm/) wrote an essay ([palm-on-being-palm.md](../../examples/adventure-4/pub/stage/palm-nook/study/palm-on-being-palm.md)) about being a monkey. ``` ### Use Tables for Related Files ```markdown ### Files Created | File | Description | |------|-------------| | [CHARACTER.yml](../../examples/adventure-4/characters/animals/monkey-palm/CHARACTER.yml) | Soul file | | `physical:` in [CHARACTER.yml](../../examples/adventure-4/characters/animals/monkey-palm/CHARACTER.yml) | Physical description | | [→ Full directory](../../examples/adventure-4/characters/animals/monkey-palm/) | Complete character | ### Related Skills | Skill | Purpose | |-------|---------| | [incarnation]($SKILLS/incarnation/) | Character creation protocol | | [speed-of-light]($SKILLS/speed-of-light/) | Multi-agent simulation | ``` > **Path variables in YAML vs Markdown:** Use `$SKILLS/` in YAML files (runtime resolution). > Use relative paths in Markdown for GitHub rendering. --- ## 📈 Tables Tell Stories Tables are excellent for: - **Summarizing actions** — turns, outcomes, stats - **Showing state** — inventories, relationships, locations - **Listing files** — what was created, edited, linked - **Character rosters** — who's present, their status ```markdown ## Current Status | Character | Location | Status | |-----------|----------|--------| | [Don](../../examples/adventure-4/characters/real-people/don-hopkins/) | pub/ | Active | | [Palm](../../examples/adventure-4/characters/animals/monkey-palm/) | stage/palm-nook/ | Writing | | [Biscuit](../../examples/adventure-4/characters/animals/dog-biscuit/) | following Don | WIGGLING | ## Session Statistics | Metric | Value | |--------|-------| | Turns | 33 | | NPCs encountered | 15 | | Relationships formed | 12 | | Gold spent | 31 | ``` ### Fold Large Tables ```markdown <details open> <summary>📂 <strong>Full inventory (47 items)</strong></summary> | Item | Location | Value | |------|----------|-------| | ... | ... | ... | </details> ``` --- ## 🔄 Retroactive Improvement **Sessions are living documents.** Every time you append: 1. **Update the index** — add new sections, fix anchors 2. **Add missing links** — file paths, character names 3. **Improve summaries** — make them more descriptive 4. **Fill in context** — as you learn more, annotate earlier sections 5. **Fix broken links** — paths change as files move ### Ninja Edits Small retroactive improvements are encouraged: - Correcting typos - Adding links to newly-created files - Improving section summaries - Updating the index --- ## 📋 YAML Data Islands Embed structured data in fenced code blocks for machine readability: ```markdown <details open> <summary>📂 <strong>State change: Moving player from start/ to coatroom/</strong></summary> ```yaml state_change: file: ./CHARACTER.yml changes: player.location: "coatroom/" # Was: "start/" file: ../../../ADVENTURE.yml changes: player.location: "coatroom/" # Mirror update ``` </details> ``` ### Data Island Best Practices | Practice | Reason | |----------|--------| | Use `# comments` | Explain the WHY, not just WHAT | | Abbreviate long data | Show structure, not everything | | Include file paths | Link to actual files | | Explain relationships | "Mirror update", "Canonical source" | --- ## 🆚 Session Logs vs Event Logs | Session Logs (SESSION.md) | Event Logs (events.yml) | |---------------------------|-------------------------| | **Human readable** | Machine readable | | **Narrative style** | Structured data | | Living document (editable) | Append-only | | Collapsible outlines | YAML events | | For reading | For debugging/audit | | In character directories | In `.agent/` or adventure root | **Create event logs** for: - Technical debugging - Append-only audit trails - Machine-parseable history **Create session logs** for: - User-facing narrative - GitHub browsing - Context warming - Storytelling --- ## 🌟 Examples: Gold Standard Sessions These sessions demonstrate best practices: ### Don Hopkins' Marathon Session [**examples/adventure-4/characters/real-people/don-hopkins/sessions/marathon-session.md**](../../examples/adventure-4/characters/real-people/don-hopkins/sessions/marathon-session.md) 7000+ lines spanning 5 days of adventure. Demonstrates: - Extensive use of collapsible sections - Comprehensive index at top - Generous linking to files and skills - Tables for menus, stats, and rosters - Speed-of-light simulation transcripts - Technical details hidden in collapsed sections ### Donna Toadstool's Session [**examples/adventure-4/characters/fictional/donna-toadstool/SESSION.md**](../../examples/adventure-4/characters/fictional/donna-toadstool/sessions/2026-01-09-birth.md) Complete character creation narrative. Demonstrates: - Table of contents with parts - Character transformation documentation - File operation explanations - Appendix with technical reference - Clear separation of narrative and data --- ## 🎯 Quick Reference ### Starting a New Section ```markdown --- <details open> <summary><h2>🌟 Turn N: Title — Descriptive Subtitle</h2></summary> Narrative description of what happened. <details open> <summary>📂 <strong>Technical: What changed under the hood</strong></summary> ```yaml changes: - file: path/to/file.yml field: value ``` </details> </details> ``` ### Checklist for Every Append - [ ] Updated index at top with new section - [ ] Added links to all mentioned files - [ ] Linked character names to their directories - [ ] Used collapsible sections appropriately - [ ] Wrote descriptive summary lines