# The reference.md Pattern

Every directory in `references/` must have a `reference.md` file. It's the routing layer that tells the AI what's here and when to go deeper.

## Purpose

The reference.md file answers three questions:
1. What knowledge lives in this directory?
2. When should I read each file?
3. Do I need to go deeper into subdirectories?

## Required sections

### What's here

A table listing each file/subdirectory with:
- Name
- Purpose (one line)
- When to read it

```markdown
## What's here

| File | Purpose | When to read |
|------|---------|--------------|
| `foo.md` | Explains X | When doing Y |
| `bar/` | Details about Z | When you need deep Z knowledge |
```

### When to use this module

Brief description of the scenarios where this directory's knowledge applies.

### Model guidance

Hints about whether cheap or stronger models should handle this content.

## Optional sections

- **Prerequisites**: What the AI should know/have before reading this
- **Child topics**: If subdirectories exist, brief descriptions of when to descend

## Anti-patterns

- Don't duplicate knowledge from child files in reference.md
- Don't make reference.md longer than ~50 lines
- Don't skip the "when to read" column - it's the whole point

## Example

```markdown
# Authentication References

## What's here

| File | Purpose | When to read |
|------|---------|--------------|
| `oauth-flow.md` | OAuth 2.0 implementation details | When the API uses OAuth |
| `api-keys.md` | API key authentication patterns | When the API uses simple API keys |
| `rate-limiting.md` | How to handle rate limits | After auth is working, before production |

## When to use this module

You're implementing authentication for an API wrapper and need to understand the auth mechanism.

## Model guidance

Factual/procedural content. Cheap model is fine.
```