# Documentation Guidelines

> How to maintain and extend the `doc/` directory for future AI agents and developers.

## Principles

1. **Load only what you need.** Each doc is self-contained for its topic. No doc should require reading other docs to be useful.
2. **One topic per file.** Don't merge unrelated topics. Create a new file instead.
3. **Keyword-searchable.** Every new doc must be added to `keywords.md`.
4. **Code examples over prose.** Show the API call, not a paragraph explaining it.
5. **Keep it current.** When you change code, update the corresponding doc.

---

## Directory Structure

```
doc/
├── INDEX.md           ← Main entry point (TOC + quick nav)
├── keywords.md        ← Keyword search index (MUST update)
├── CONTRIBUTING.md    ← This file
├── formats/           ← File format specifications (binary/protocol level)
├── api/               ← PHP API documentation (how to use the code)
└── internal/          ← Development notes (learnings, decisions, issues)
```

### When to use which directory

| Directory | Content | Example |
|-----------|---------|---------|
| `formats/` | Binary file format specs, protobuf structure, encoding details | `pp_song_spec.md`, `pp_playlist_spec.md` |
| `api/` | PHP class usage, method signatures, code examples | `song.md`, `playlist.md` |
| `internal/` | Dev notes that help debug or understand history | `learnings.md`, `decisions.md`, `issues.md` |

---

## Adding a New Document

### Step 1: Create the file

Place it in the correct directory based on content type (see above).

### Step 2: Update INDEX.md

Add a line to the Table of Contents section under the appropriate heading:

```markdown
### File Format Specifications
- [formats/new_format_spec.md](formats/new_format_spec.md) -- Description
```

### Step 3: Update keywords.md

Add entries for EVERY searchable keyword in your doc:

```markdown
## New Category

| Keyword | Document |
|---------|----------|
| keyword1 | [path/to/doc.md](path/to/doc.md) |
| keyword2 | [path/to/doc.md](path/to/doc.md) Section N |
```

If your keywords fit existing categories, add them there instead.

### Step 4: Cross-reference

If your doc relates to existing docs, add a "See Also" section at the bottom:

```markdown
## See Also

- [Related Doc](../path/to/related.md) -- Why it's related
```

---

## Document Template

```markdown
# Title

> One-line summary of what this doc covers.

## Quick Reference

\`\`\`php
// Most common usage pattern (2-5 lines)
\`\`\`

---

## Section 1

Content with code examples.

---

## Section 2

More content.

---

## Key Files

| File | Purpose |
|------|---------|
| `path/to/file.php` | What it does |

---

## See Also

- [Related Doc](../path/to/related.md)
```

---

## Style Guide

### Headings
- `#` for document title (one per file)
- `##` for main sections
- `###` for subsections
- Use `---` horizontal rules between major sections

### Code Blocks
- Always specify language: ` ```php `, ` ```bash `, ` ```markdown `
- Show complete, runnable examples (not fragments)
- Include the `use` statements on first occurrence

### Tables
- Use tables for reference data (fields, files, options)
- Left-align text columns, include header row

### Tone
- Direct. No filler words.
- "Use X to do Y" not "You can use X to do Y"
- Show code first, explain after (only if needed)

---

## Updating Existing Docs

When modifying the codebase:

1. **New PHP method** → Update the corresponding `api/*.md`
2. **New file format discovery** → Update `formats/*.md`
3. **Architecture change** → Update `internal/decisions.md`
4. **Bug/gotcha found** → Update `internal/issues.md`
5. **Any change** → Check `keywords.md` for new keywords

---

## AI Agent Instructions

When AGENTS.md tells you to load docs, follow these steps:

1. Read `doc/INDEX.md` to understand what's available
2. Identify which docs match your task (use `keywords.md` if unsure)
3. Load ONLY the relevant docs
4. Do NOT load everything -- context window is precious

### Loading patterns

```
Task: "Parse a song"           → Load: doc/api/song.md
Task: "Fix protobuf parsing"   → Load: doc/formats/pp_song_spec.md
Task: "Create a playlist"      → Load: doc/api/playlist.md
Task: "Debug ZIP issues"       → Load: doc/formats/pp_playlist_spec.md + doc/internal/issues.md
Task: "Add new feature"        → Load: relevant api/ doc + doc/CONTRIBUTING.md
```