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:

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

<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>

The YAML data island

state_change: file: ./CHARACTER.yml changes: [location, inventory]

</details>

</details>

Outline Patterns

The Summary Line

The <summary> is part of the narrative! Write it as a headline:

<!-- 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:

📊 Session Index

Keep an index at the top of every session! Update it retroactively as you append.

<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

<!-- 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

### 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

## 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

<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:

<details open>
<summary>📂 <strong>State change: Moving player from start/ to coatroom/</strong></summary>

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

🆚 Session Logs vs Event Logs

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

---

<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>

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
• Included relevant tables
• Fixed any broken links noticed

The Intertwingularity

Session-log is the PLAY stage of [play-learn-lift](../play-learn-lift/) — capture everything.

graph LR
    SL[📜 session-log] -->|PLAY stage of| PLL[🎮 play-learn-lift]
    SL -->|tracks| R[🚪 room]
    SL -->|tracks| TC[🎴 card]
    SL -->|monitored by| SR[🔧 self-repair]
    
    AP[⚔️ adventure] -->|LOG.md is| SL
    DB[🔧 debugging] -->|logs to| SL
    CH[👤 character] -->|SESSION.md is| SL

Dovetails With

Sister Skills

Protocol Symbols

Kernel

• [kernel/event-logging-protocol.md](../../kernel/event-logging-protocol.md) — Technical event format
• [schemas/event-schema.yml](../../schemas/event-schema.yml) — YAML block schema

Navigation