propresenter-php/doc/CONTRIBUTING.md

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:

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

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

## See Also

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

---

Document Template

# 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