| name | museum-documentation |
| description | Write elegant, narrative-driven documentation that treats codebases and systems as exhibits worth exploring. Use when creating documentation for Wanderers and visitors who want to understand how Grove works. This is the "fancy" documentation styleโwarm, inviting, meant to be read and enjoyed. |
Museum Documentation
Documentation as hospitality. Code as curated collection.
The art of transforming technical systems into welcoming guided tours. Museum documentation positions the writer as a guide walking alongside readers through "why" questions before diving into implementation specifics.
This is Grove's elegant documentation styleโmeant for Wanderers of any experience level who want to understand the technologies, patterns, and decisions that make Grove what it is.
When to Activate
- Creating documentation meant to be read by Wanderers, not developers
- Writing knowledge base articles that explain how systems work
- Documenting a codebase, feature, or system for curious visitors
- Creating "how it works" content for the help center
- Writing technical content that should feel inviting, not intimidating
- Building exhibits for future knowledge base sections
- Onboarding documentation that walks through architecture
Not for:
- API references (use grove-documentation)
- Technical specs (use grove-spec-writing)
- Quick-reference guides
Core Philosophy
Documentation should function as hospitality.
When readers enter a codebase or system, they're visitors unfamiliar with its architecture and design decisions. Museum-style documentation positions the writer as a guide rather than a reference compiler, walking alongside readers through "why" questions before diving into implementation.
The Museum Metaphor
๐ฒ Welcome ๐ฒ
โญโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ
โ โญโโโโโโโโโโโโโโฎ โ
โ โ EXHIBIT A โ โ
โ โ โ โ
โ โ How Login โ โ
โ โ Works โ โ
โ โ โ โ
โ โฐโโโโโโโโโโโโโโฏ โ
โ โ โ
โ โโโโโโชโโโโโ โ
โ โ โ
โ โญโโโโโโโโโโโโโโฎ โ
โ โ EXHIBIT B โ โ
โ โฐโโโโโโโโโโโโโโฏ โ
โ โ
โฐโโโโโโโโโโโโโโโโโโโโโโฏ
Walk through. Take your time.
Every exhibit tells a story.
A museum doesn't hand you a catalog and wish you luck. It guides you through a curated experience, placing context before complexity, stories before specifications.
Key Principles
Orient Before Explaining
Start exhibits by establishing context. Before showing code or architecture, tell readers:
- What they're looking at
- Why it exists
- Who benefits from it
Instead of:
The TokenRefreshMap stores active refresh operations keyed by user ID.
Write:
When someone's login expires, we need to refresh their credentials without logging them out. This map coordinates that processโpreventing duplicate refresh attempts when multiple tabs are open.
Explain Reasoning Over Facts
Code shows what. Documentation explains why.
Rather than stating that a Map stores token refresh operations, describe the coordination problem it solves. Connect the abstraction to the experience it creates.
Use Accessible Metaphors
Connect technical concepts to familiar experiences:
| Technical Concept | Museum Metaphor |
|---|
| Database | A filing cabinet with organized drawers |
| Cache | A quick-lookup shelf by the door |
| Middleware | A security checkpoint you pass through |
| Queue | A line where requests wait their turn |
| Worker | A helpful assistant handling tasks in the background |
| Webhook | A doorbell that rings when something happens |
Show Real Code, Then Analyze
Present actual code snippets followed by clear explanation of their significance:
const pending = this.refreshInProgress.get(userId);
if (pending) return pending;
If a refresh is already happening for this person, we wait for that one instead of starting another. One kitchen, one cook.
Structural Framework
Museum exhibits follow consistent anatomy:
1. Title with Tagline
# The Authentication Exhibit
> Where login happens. Where trust begins.
2. "What You're Looking At" Section
Orient the reader immediately:
## What You're Looking At
This is where login happens. When someone proves they own an email
address, this code decides what they can access and how long that
access lasts.
You'll see OAuth flows, session management, and token refresh logic.
Nothing scaryโjust careful choreography.
3. Organized Tour Structure
Use galleries, parts, or sections to organize the journey:
## The Tour
### Gallery 1: The Front Door
How visitors arrive and prove who they are.
### Gallery 2: The Memory Room
How we remember who's logged in.
### Gallery 3: The Renewal Office
How sessions stay fresh without interrupting work.
4. "Patterns Worth Stealing"
Highlight transferable lessons:
## Patterns Worth Stealing
**The "already in progress" check.** Before starting an expensive
operation, check if it's already running. Simple, but easy to forget.
**Centralized error handling.** All auth failures flow through one
function. One place to fix, one place to log.
5. "Lessons Learned"
Offer honest reflection:
## Lessons Learned
We tried stateless JWTs first. Simpler, they said. Scalable, they
promised. But logout was impossibleโtokens couldn't be revoked.
Session-based auth is older, but it works. Sometimes boring is right.
6. "Continue Your Tour"
Link to related exhibits:
## Continue Your Tour
- **[The Database Exhibit](./database.md)** โ Where sessions are stored
- **[The API Exhibit](./api.md)** โ How protected routes check access
- **[The Security Exhibit](./security.md)** โ Rate limiting and protection
7. Meaningful Closing Signature
---
_โ Autumn, January 2026_
Or a poetic one-liner:
---
_Trust is built one verified request at a time._
Visual Elements
ASCII Flow Diagrams
Show processes and relationships:
Visitor Grove Google
โ โ โ
โ "Log me in" โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโ>โ โ
โ โ "Who is this?" โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโ>โ
โ โ โ
โ โ "It's autumn@..." โ
โ โ <โโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ โ
โ "Welcome back" โ โ
โ <โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
Tables for Quick Reference
| File | What It Does | Why It Matters |
| --------------- | -------------------- | -------------- |
| `auth.ts` | Handles OAuth flow | The front door |
| `session.ts` | Manages login state | The memory |
| `middleware.ts` | Checks every request | The bouncer |
Code Blocks with Context
Never show code in isolation. Always explain before or after:
export async function authGuard(request: Request): Promise<Response | null> {
const session = await getSession(request);
if (!session) {
return redirect("/login");
}
return null;
}
If you're not logged in, you go to login. If you are, you continue. Simple checkpoint logic.
Voice and Tone
Do
- Write conversationally using "you" and "we" naturally
- Acknowledge imperfections ("We tried X first. It didn't work.")
- Include personal touches ("This took three attempts to get right.")
- Use short paragraphs (2-4 sentences)
- Vary sentence rhythm
Avoid
Refer to owl-archive/references/anti-patterns.md for the full list. Key ones for museum writing:
- Em-dashes (use periods, commas, or parentheses)
- Corporate jargon ("robust," "seamless," "leverage," "utilize," "streamline")
- Heavy transitions ("Furthermore," "Moreover," "Additionally," "It's worth noting")
- The "Not X, but Y" pattern and its variants ("Not X. Not Y. Just Z.")
- Passive voice when active is clearer
- Hedging language ("This may potentially help...")
- Dead metaphors (don't repeat the same metaphor in every paragraph)
- Fractal summaries (don't preview, state, then re-summarize every section)
- "Here's the thing" / "Here's the kicker" false suspense
- Gerund fragment litanies ("Fixing bugs. Writing features. Shipping code.")
- Historical analogy stacking ("Apple... Facebook... Uber..." rapid-fire)
- Bold-first bullet patterns in narrative lists
The Distinction
Generic (avoid):
This module provides robust functionality for handling authentication flows in a seamless manner, leveraging industry-standard OAuth protocols.
Museum style (use):
This is where login happens. When someone proves they own an email address, this code decides what they can access.
Organization Patterns
Full Codebase: MUSEUM.md
For documenting an entire codebase, create a central MUSEUM.md that serves as the entrance:
# Welcome to the Grove Museum
> A guided tour of how this forest grows.
## The Wings
- **[The Architecture Wing](./docs/exhibits/architecture.md)** โ The big picture
- **[The Authentication Exhibit](./docs/exhibits/auth.md)** โ Trust and identity
- **[The Database Galleries](./docs/exhibits/database.md)** โ Where data lives
Single Directory: EXHIBIT.md
For a single complex feature or directory:
# The Editor Exhibit
> Where words become posts.
This directory contains everything that powers the writing experience...
Complex Features: Gallery Structure
For multi-part systems, use galleries:
## Gallery 1: Data Layer
How posts are stored and retrieved.
## Gallery 2: API Endpoints
The doors visitors knock on.
## Gallery 3: The Editor Component
Where the magic happens in the browser.
## Gallery 4: Security Considerations
Keeping things safe.
Validation Checklist
Before finalizing any museum documentation:
Structure
Visual Variety
Voice (refer to grove-documentation)
Reader Experience
Integration with Other Skills
Before Writing
- walking-through-the-grove โ If the exhibit needs a name
- grove-documentation โ Review voice guidelines, especially the "avoid" lists
While Writing
- grove-spec-writing โ Borrow ASCII art techniques for diagrams
- grove-documentation โ Check terminology (Wanderer, Rooted, etc.)
- GroveTerm components โ When exhibits include Grove terminology in UI, use
GroveTerm, GroveSwap, or GroveText from @autumnsgrove/lattice/ui instead of hardcoding terms. New visitors see standard terms by default; Grove Mode users see the nature-themed vocabulary. Use [[term]] syntax in markdown content for auto-transformation via the rehype-groveterm plugin.
After Writing
- Read as a newcomer โ Traverse the documentation as if you've never seen it
- Does the path feel logical? Would you want to explore further?
Example: A Complete Exhibit
# The Session Exhibit
> How Grove remembers who you are.
## What You're Looking At
When you log in, Grove needs to remember you. Not foreverโjust long
enough for your visit. This exhibit shows how that memory works.
You'll see cookies, database tables, and the careful dance of
"who are you?" that happens with every page load.
---
## Gallery 1: The Cookie Jar
A session starts with a cookie. Not the chocolate chip kindโa small
piece of text your browser holds onto.
```typescript
const SESSION_COOKIE = "grove_session";
const SESSION_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days
```
Seven days. Long enough to be convenient, short enough to stay secure.
When you log in, we generate a random ID and store it in this cookie.
The ID itself means nothingโit's just a key to look you up.
Gallery 2: The Memory Book
The actual session data lives in the database:
| Column | What It Holds |
|---|
id | The random key from the cookie |
user_id | Who this session belongs to |
created_at | When you logged in |
expires_at | When this session ends |
Every time you load a page, we look up your cookie's ID in this table.
If we find it (and it hasn't expired), you're still logged in.
Gallery 3: The Refresh Dance
Sessions expire. But logging in every week is annoying.
So we do a quiet refresh: when your session is more than halfway
through its life, we extend it. You never notice. You just stay
logged in while you're active.
if (session.expiresAt < Date.now() + SESSION_DURATION / 2) {
await extendSession(session.id);
}
Active visitors stay. Abandoned sessions expire.
Patterns Worth Stealing
The "halfway refresh" pattern. Don't wait until expiration to
extend sessions. Extend them while the visitor is active.
Random IDs over sequential. Session IDs should be unpredictable.
Never use auto-incrementing numbers for security tokens.
Lessons Learned
We used to store session data in the cookie itself (JWTs). Simpler,
we thought. But then we couldn't revoke sessionsโif someone's token
leaked, we had no way to invalidate it.
Database sessions are older technology. Sometimes older is wiser.
Continue Your Tour
โ Autumn, January 2026
---
## The Underlying Purpose
Museum documentation respects readers' time and intelligence while acknowledging that code is knowledge deserving careful stewardship.
Wanderers who read these exhibits should leave understanding not just *what* Grove does, but *why* it does it that way. They should feel like they've been welcomed into the workshop, not handed a manual.
*Every codebase has stories. Museum documentation tells them.*
