docs: use Diátaxis structure

1 files changed, 201 insertions, 0 deletions

diff --git a/docs/reference/README.md b/docs/reference/README.md
new file mode 100644
index 0000000..96fc5ed
--- /dev/null
+++ b/docs/reference/README.md
@@ -0,0 +1,201 @@
+# Reference
+
+**Information-oriented documentation** - Technical details and specifications.
+
+---
+
+## What Is Reference Documentation?
+
+Reference documentation provides **factual, technical information** that you look up when needed.
+
+**Characteristics:**
+- ✅ Information-oriented (facts and data)
+- ✅ Comprehensive and accurate
+- ✅ Structured for lookup
+- ✅ Dry and to-the-point
+- ✅ Maintained as code changes
+
+**Not reference:**
+- ❌ Learning materials (those are Tutorials)
+- ❌ Problem-solving guides (those are How-To)
+- ❌ Conceptual explanations (those are Explanation)
+
+---
+
+## Available Reference Documentation
+
+### [Configuration](configuration.md)
+**Complete reference for all configuration options**
+
+**Contents:**
+- Environment variables
+- Configuration file format
+- Validation rules
+- Examples for development/production/testing
+
+**Use when:** You need to know what a config option does or what values are valid
+
+---
+
+### [Git Protocol](git-protocol.md)
+**Git Smart HTTP protocol specification**
+
+**Contents:**
+- Protocol overview
+- Pkt-line format
+- Request/response structure
+- Reference updates format
+- Parsing examples
+
+**Use when:** You need to understand Git HTTP internals
+
+---
+
+### [Test Strategy](test-strategy.md)
+**Testing approach and compliance framework**
+
+**Contents:**
+- Test categories (unit, integration, compliance)
+- GRASP compliance requirements
+- Test isolation strategy
+- Running tests
+- Coverage requirements
+
+**Use when:** You're writing tests or need to understand test structure
+
+---
+
+## Planned Reference Documentation
+
+### GRASP Protocol
+**Status:** 🔜 Planned
+
+**Contents:**
+- GRASP-01 requirements
+- GRASP-02 (Proactive Sync)
+- GRASP-05 (Archive)
+- Event formats
+- Validation rules
+
+---
+
+### API Reference
+**Status:** 🔜 Planned (waiting for main server)
+
+**Contents:**
+- HTTP endpoints
+- Request/response formats
+- Error codes
+- Authentication
+- Rate limiting
+
+---
+
+### nostr-sdk Upgrade Guide
+**Status:** 🔜 Planned
+
+**Contents:**
+- Version compatibility matrix
+- Breaking changes by version
+- Migration examples
+- Common patterns
+
+---
+
+### Event Formats
+**Status:** 🔜 Planned
+
+**Contents:**
+- NIP-34 repository announcements (kind 30317)
+- NIP-34 state events (kind 30318)
+- Custom tags
+- Validation rules
+
+---
+
+### CLI Reference
+**Status:** 🔜 Planned
+
+**Contents:**
+- Command-line arguments
+- Subcommands
+- Environment variables
+- Exit codes
+
+---
+
+## How to Use Reference Documentation
+
+1. **Know what you're looking for** - Reference is for lookup, not learning
+2. **Use search or table of contents** - Find the specific detail you need
+3. **Check version** - Ensure docs match your version
+4. **Verify with code** - Reference should match implementation
+
+**Not sure if this is what you need?**
+- New to the topic? → [Tutorials](../tutorials/)
+- Trying to solve a problem? → [How-To Guides](../how-to/)
+- Want to understand concepts? → [Explanation](../explanation/)
+
+---
+
+## Contributing Reference Documentation
+
+When writing reference documentation:
+
+**DO:**
+- ✅ Be accurate and complete
+- ✅ Use consistent structure
+- ✅ Include all options/parameters
+- ✅ Provide examples
+- ✅ Update when code changes
+- ✅ Use tables for structured data
+
+**DON'T:**
+- ❌ Explain concepts (link to Explanation)
+- ❌ Provide tutorials (link to Tutorials)
+- ❌ Solve problems (link to How-To)
+- ❌ Include opinions or recommendations
+
+**Template:**
+```markdown
+# Reference: [Topic]
+
+**Purpose:** [What this reference covers]  
+**Audience:** [Who needs this information]
+
+---
+
+## Overview
+
+[Brief description of what's being documented]
+
+---
+
+## [Section 1]
+
+### [Item]
+
+**Description:** [What it is/does]  
+**Type:** [Data type]  
+**Default:** [Default value]  
+**Required:** [Yes/No]
+
+**Examples:**
+\`\`\`
+[Example usage]
+\`\`\`
+
+**Notes:**
+- [Important details]
+
+---
+
+## Related Documentation
+- [Links to relevant docs]
+```
+
+See [Diátaxis: Reference](https://diataxis.fr/reference/) for detailed guidance.
+
+---
+
+*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*