1 files changed, 147 insertions, 64 deletions

diff --git a/docs/README.md b/docs/README.md
index 745211d..ab02cb9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,84 +1,167 @@
 # ngit-grasp Documentation
 
-## Overview
+Welcome to the **ngit-grasp** documentation! We use the [Diátaxis](https://diataxis.fr/) framework to organize our documentation into four types, each serving a different purpose.
+
+```
+                    PRACTICAL          THEORETICAL
+                    ─────────          ───────────
+                    
+LEARNING      │   Tutorials    │    Explanation   │
+              │                │                  │
+              │  Getting       │   Architecture   │
+              │  Started       │   Decisions      │
+              │                │                  │
+              ├────────────────┼──────────────────┤
+              │                │                  │
+WORKING       │  How-To        │    Reference     │
+              │  Guides        │                  │
+              │                │   API Docs       │
+              │  Deployment    │   Protocols      │
+              │  Testing       │                  │
+              │                │                  │
+```
+
+## 📚 Documentation Types
+
+### 🎓 [Tutorials](tutorials/) - *Learning by Doing*
+**Purpose:** Learn the basics through practical steps  
+**For:** Newcomers getting started  
+**Style:** Step-by-step lessons with guaranteed outcomes
+
+- **[Getting Started](tutorials/getting-started.md)** - Your first ngit-grasp setup
+- **[Running Your First Audit](tutorials/first-audit.md)** - Using grasp-audit tool
+
+### 🔧 [How-To Guides](how-to/) - *Solving Problems*
+**Purpose:** Accomplish specific tasks  
+**For:** Users with basic knowledge solving real problems  
+**Style:** Practical recipes and solutions
+
+- **[Deploy ngit-grasp](how-to/deploy.md)** - Production deployment guide
+- **[Configure Nix Flakes](how-to/nix-flakes.md)** - Nix development environment
+- **[Run Compliance Tests](how-to/test-compliance.md)** - GRASP compliance testing
+- **[Upgrade nostr-sdk](how-to/upgrade-nostr-sdk.md)** - Handling SDK upgrades
+
+### 📖 [Reference](reference/) - *Technical Information*
+**Purpose:** Look up technical details  
+**For:** Users who know what they're looking for  
+**Style:** Dry, factual, comprehensive
+
+- **[Git Protocol](reference/git-protocol.md)** - Git Smart HTTP protocol details
+- **[GRASP Protocol](reference/grasp-protocol.md)** - GRASP specification details
+- **[Configuration](reference/configuration.md)** - All config options
+- **[API Reference](reference/api.md)** - Internal API documentation
+
+### 💡 [Explanation](explanation/) - *Understanding Concepts*
+**Purpose:** Understand the "why" and design decisions  
+**For:** Users wanting deeper understanding  
+**Style:** Discussion, context, alternatives
+
+- **[Architecture Overview](explanation/architecture.md)** - System design and components
+- **[Inline Authorization](explanation/inline-authorization.md)** - Why we chose this approach
+- **[Comparison with ngit-relay](explanation/comparison.md)** - How we differ from reference
+- **[Design Decisions](explanation/decisions.md)** - Key architectural choices
+
+---
 
-This directory contains comprehensive documentation for the ngit-grasp project.
+## 🚀 Quick Start Paths
+
+### I'm brand new to ngit-grasp
+1. Read [README.md](../README.md) for project overview
+2. Follow [Getting Started Tutorial](tutorials/getting-started.md)
+3. Understand [Architecture Overview](explanation/architecture.md)
+
+### I want to deploy ngit-grasp
+1. Review [Configuration Reference](reference/configuration.md)
+2. Follow [Deployment How-To](how-to/deploy.md)
+3. Set up monitoring and backups
+
+### I want to develop on ngit-grasp
+1. Follow [Getting Started Tutorial](tutorials/getting-started.md)
+2. Read [Architecture Overview](explanation/architecture.md)
+3. Check [Nix Flakes How-To](how-to/nix-flakes.md)
+4. Review [Test Strategy](how-to/test-compliance.md)
+
+### I want to understand the design
+1. Read [Inline Authorization Explanation](explanation/inline-authorization.md)
+2. Review [Design Decisions](explanation/decisions.md)
+3. Compare with [ngit-relay Comparison](explanation/comparison.md)
+
+### I'm looking for specific information
+- **Protocol details?** → [Reference](reference/)
+- **Configuration options?** → [Configuration Reference](reference/configuration.md)
+- **Git protocol?** → [Git Protocol Reference](reference/git-protocol.md)
+
+---
+
+## 📂 Additional Resources
+
+### [Archive](archive/)
+Historical session notes and completed work. Useful for understanding project evolution but not required reading.
+
+### [Learnings](learnings/)
+**DEPRECATED** - Being migrated to Diátaxis structure:
+- Gotchas → How-To Guides
+- Patterns → Reference or Explanation
+- Notes → Appropriate category
+
+---
+
+## 🤝 Contributing to Documentation
 
-## Documents
+When adding documentation, ask yourself:
 
-### For Review
-- **[../REVIEW_SUMMARY.md](../REVIEW_SUMMARY.md)** - Start here! Executive summary of the architecture investigation and recommendations
+**Is it a tutorial?**
+- Does it teach a beginner?
+- Is it a complete lesson with guaranteed outcome?
+- → Add to `tutorials/`
 
-### Architecture & Design
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed technical architecture, component design, data flows, and implementation details
-- **[DECISION_SUMMARY.md](DECISION_SUMMARY.md)** - Why we chose inline authorization over Git hooks
-- **[COMPARISON.md](COMPARISON.md)** - Side-by-side comparison with the reference implementation (ngit-relay)
+**Is it a how-to guide?**
+- Does it solve a specific problem?
+- Is it a recipe for accomplishing a task?
+- → Add to `how-to/`
 
-### Technical References
-- **[GIT_PROTOCOL.md](GIT_PROTOCOL.md)** - Git Smart HTTP protocol reference, pkt-line format, and parsing examples
-- **[TEST_STRATEGY.md](TEST_STRATEGY.md)** - Comprehensive testing strategy including reusable GRASP compliance testing tool
+**Is it reference material?**
+- Is it technical information?
+- Will people look it up when needed?
+- → Add to `reference/`
 
-### Project Files
-- **[../README.md](../README.md)** - Project overview, quick start, and feature list
-- **[../.env.example](../.env.example)** - Configuration template
-- **[../LICENSE](../LICENSE)** - MIT License
+**Is it explanation?**
+- Does it explain "why"?
+- Does it discuss alternatives or design?
+- → Add to `explanation/`
 
-## Reading Guide
+See [Diátaxis documentation](https://diataxis.fr/) for more guidance.
 
-### If you want to understand the architecture decision:
-1. Read [REVIEW_SUMMARY.md](../REVIEW_SUMMARY.md) - Executive summary
-2. Read [DECISION_SUMMARY.md](DECISION_SUMMARY.md) - Detailed rationale
-3. Skim [COMPARISON.md](COMPARISON.md) - See how we differ from reference
+---
 
-### If you want to implement:
-1. Read [ARCHITECTURE.md](ARCHITECTURE.md) - Component design and code structure
-2. Read [TEST_STRATEGY.md](TEST_STRATEGY.md) - Testing approach and compliance tool
-3. Read [GIT_PROTOCOL.md](GIT_PROTOCOL.md) - Git protocol details
-4. Review code examples in ARCHITECTURE.md
+## 📊 Project Status
 
-### If you want to deploy:
-1. Read [README.md](../README.md) - Quick start
-2. Review [.env.example](../.env.example) - Configuration
-3. See deployment section in [ARCHITECTURE.md](ARCHITECTURE.md)
+**ALPHA** - Under active development. Core functionality working, API may change.
 
-### If you're comparing with ngit-relay:
-1. Read [COMPARISON.md](COMPARISON.md) - Detailed comparison
-2. See architecture diagrams in both COMPARISON.md and ARCHITECTURE.md
+### Completed
+- ✅ grasp-audit compliance testing tool
+- ✅ Nix flake development environment
+- ✅ nostr-sdk 0.43 upgrade
+- ✅ Documentation restructure (Diátaxis)
 
-## Key Concepts
+### In Progress
+- 🔄 Core ngit-grasp server implementation
+- 🔄 GRASP-01 compliance
 
-### Inline Authorization
-The core architectural decision: we validate Git pushes **inside the HTTP handler** before spawning Git, rather than using Git's pre-receive hooks.
+### Planned
+- 🔜 GRASP-02 (Proactive Sync)
+- 🔜 GRASP-05 (Archive)
 
-**Benefits:**
-- Better error messages (HTTP responses vs. hook stderr)
-- Simpler deployment (no hook management)
-- Easier testing (pure Rust)
-- Better performance (skip Git for invalid pushes)
+---
 
-### GRASP Protocol
-Git Relays Authorized via Signed-Nostr Proofs - a protocol for hosting Git repositories with Nostr-based authorization.
+## 🔗 External Links
 
-**Key Points:**
-- Repository announcements (NIP-34 kind 30317)
-- State announcements (NIP-34 kind 30318)
-- Multi-maintainer support via recursive maintainer sets
-- Push validation against signed state events
+- [GRASP Protocol Specification](https://gitworkshop.dev/danconwaydev.com/grasp)
+- [NIP-34 (Git Stuff)](https://nips.nostr.com/34)
+- [Diátaxis Framework](https://diataxis.fr/)
+- [rust-nostr Documentation](https://docs.rs/nostr-sdk/)
 
-### Technology Stack
-- **actix-web**: HTTP server
-- **git-http-backend**: Git protocol handling (Rust crate)
-- **nostr-relay-builder**: Nostr relay infrastructure (rust-nostr)
-- **tokio**: Async runtime
+---
 
-## Status
-
-**ALPHA** - Architecture design complete, implementation not yet started.
-
-## Contributing
-
-See [../README.md](../README.md) for contribution guidelines.
-
-## Questions?
-
-Open an issue or discussion on the repository.
+*Documentation structure based on [Diátaxis](https://diataxis.fr/)*  
+*Last updated: November 4, 2025*