docs: use Diátaxis structure

5 files changed, 1866 insertions, 0 deletions

diff --git a/docs/explanation/README.md b/docs/explanation/README.md
new file mode 100644
index 0000000..cc3ec49
--- /dev/null
+++ b/docs/explanation/README.md
@@ -0,0 +1,225 @@
+# Explanation
+
+**Understanding-oriented documentation** - Concepts, design decisions, and the "why" behind ngit-grasp.
+
+---
+
+## What Is Explanation?
+
+Explanation documentation helps you **understand concepts** and design decisions, providing context and discussing alternatives.
+
+**Characteristics:**
+- ✅ Understanding-oriented (clarify concepts)
+- ✅ Theoretical (ideas and design)
+- ✅ Discuss alternatives
+- ✅ Provide context and background
+- ✅ Answer "why" questions
+
+**Not explanation:**
+- ❌ Step-by-step lessons (those are Tutorials)
+- ❌ Problem-solving recipes (those are How-To)
+- ❌ Technical specifications (those are Reference)
+
+---
+
+## Available Explanation Documentation
+
+### [Architecture Overview](architecture.md)
+**Understand the system design and component interaction**
+
+**Topics:**
+- Overall architecture
+- Component responsibilities
+- Data flows
+- Technology choices
+- Design patterns
+
+**Read when:** You want to understand how ngit-grasp works as a system
+
+---
+
+### [Inline Authorization](inline-authorization.md)
+**Why we validate pushes inline instead of using Git hooks**
+
+**Topics:**
+- The authorization problem
+- Git hooks approach
+- Inline approach
+- Comparison and trade-offs
+- Implementation details
+
+**Read when:** You want to understand the core architectural decision
+
+---
+
+### [Design Decisions](decisions.md)
+**Key architectural choices and their rationale**
+
+**Topics:**
+- Inline authorization vs hooks
+- Technology stack choices
+- Storage design
+- API design
+- Performance considerations
+
+**Read when:** You want to know why things are the way they are
+
+---
+
+### [Comparison with ngit-relay](comparison.md)
+**How ngit-grasp differs from the reference implementation**
+
+**Topics:**
+- Architecture comparison
+- Component differences
+- Trade-offs
+- Migration path
+- Compatibility
+
+**Read when:** You're familiar with ngit-relay and want to understand differences
+
+---
+
+## Planned Explanation Documentation
+
+### GRASP Protocol Design
+**Status:** 🔜 Planned
+
+**Topics:**
+- Why Nostr for Git?
+- Authorization model
+- Trust and verification
+- Decentralization benefits
+
+---
+
+### Storage Architecture
+**Status:** 🔜 Planned
+
+**Topics:**
+- Why separate Git and Nostr storage?
+- Indexing strategy
+- Performance considerations
+- Scaling approach
+
+---
+
+### Testing Philosophy
+**Status:** 🔜 Planned
+
+**Topics:**
+- Why test isolation?
+- Integration vs unit tests
+- Compliance testing approach
+- Test-driven development
+
+---
+
+### Performance Considerations
+**Status:** 🔜 Planned
+
+**Topics:**
+- Async architecture
+- Caching strategy
+- Database choices
+- Bottlenecks and solutions
+
+---
+
+## How to Use Explanation Documentation
+
+1. **Read to understand** - Not to accomplish a task
+2. **Follow your curiosity** - Read what interests you
+3. **Connect concepts** - Link ideas together
+4. **Question and explore** - Think critically
+
+**Not sure if this is what you need?**
+- Want to learn by doing? → [Tutorials](../tutorials/)
+- Need to solve a problem? → [How-To Guides](../how-to/)
+- Looking for technical details? → [Reference](../reference/)
+
+---
+
+## Contributing Explanation Documentation
+
+When writing explanation:
+
+**DO:**
+- ✅ Discuss concepts and ideas
+- ✅ Provide context and background
+- ✅ Explain alternatives
+- ✅ Use analogies and examples
+- ✅ Connect to broader context
+- ✅ Answer "why" questions
+
+**DON'T:**
+- ❌ Provide step-by-step instructions (link to Tutorials/How-To)
+- ❌ List technical details (link to Reference)
+- ❌ Assume you must be comprehensive
+- ❌ Avoid opinions (explanation can be opinionated)
+
+**Template:**
+```markdown
+# Explanation: [Topic]
+
+**Purpose:** [What concept/decision this explains]  
+**Audience:** [Who wants to understand this]
+
+---
+
+## The Problem/Question
+
+[What are we trying to understand?]
+
+---
+
+## Background
+
+[Context and history]
+
+---
+
+## Our Approach
+
+[How we address it]
+
+### Why This Works
+
+[Explanation of benefits]
+
+### Trade-offs
+
+[What we gain and lose]
+
+---
+
+## Alternatives Considered
+
+### [Alternative 1]
+
+**Pros:**
+- [Benefits]
+
+**Cons:**
+- [Drawbacks]
+
+**Why we didn't choose it:**
+[Reasoning]
+
+---
+
+## Conclusion
+
+[Summary of understanding]
+
+---
+
+## Related Documentation
+- [Links to relevant docs]
+```
+
+See [Diátaxis: Explanation](https://diataxis.fr/explanation/) for detailed guidance.
+
+---
+
+*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*
diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
new file mode 100644
index 0000000..ebf7a74
--- /dev/null
+++ b/docs/explanation/architecture.md
@@ -0,0 +1,808 @@
+# ngit-grasp Architecture
+
+## Executive Summary
+
+`ngit-grasp` implements the GRASP protocol in Rust with **inline authorization** rather than Git hooks. The key architectural insight is that the `git-http-backend` Rust crate provides sufficient flexibility to intercept and validate Git push operations before they reach the Git repository, eliminating the need for pre-receive hooks.
+
+## Architectural Decision: Inline vs. Hook-Based Authorization
+
+### Investigation Summary
+
+After examining both the reference implementation and the `git-http-backend` Rust crate, we have two options:
+
+#### Option 1: Hook-Based (Reference Implementation Approach)
+- Use `git-http-backend` crate as-is
+- Create pre-receive and post-receive hooks
+- Hooks query the Nostr relay and validate pushes
+- **Pros**: Follows reference implementation closely
+- **Cons**: Requires hook management, harder to test, less Rust-native
+
+#### Option 2: Inline Authorization (Recommended)
+- Intercept Git receive-pack requests in the HTTP handler
+- Validate against Nostr state before spawning Git process
+- Only forward valid pushes to Git
+- **Pros**: Better error handling, easier testing, pure Rust, simpler deployment
+- **Cons**: Requires custom Git protocol handling
+
+### Decision: Inline Authorization (Option 2)
+
+**Rationale:**
+
+1. **The `git-http-backend` crate is sufficiently flexible**: Examining `src/actix/git_receive_pack.rs` shows it spawns `git receive-pack` as a subprocess and streams data. We can intercept this.
+
+2. **Better Developer Experience**: 
+   - Validation errors can be returned as proper HTTP responses
+   - No need to parse hook stderr output
+   - Shared state between Git and Nostr components
+   - Pure Rust testing without shell scripts
+
+3. **Simpler Deployment**:
+   - Single binary
+   - No hook symlinks or permissions to manage
+   - No multi-process coordination
+
+4. **Performance**:
+   - Can parse incoming pack data once
+   - Avoid process spawn overhead for invalid pushes
+   - Better async integration
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        ngit-grasp                           │
+│                     (Single Rust Binary)                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────────┐              ┌──────────────────┐   │
+│  │   HTTP Router    │              │  Nostr Relay     │   │
+│  │   (actix-web)    │              │  (nostr-relay-   │   │
+│  │                  │              │   builder)       │   │
+│  └────────┬─────────┘              └────────┬─────────┘   │
+│           │                                 │             │
+│           │                                 │             │
+│  ┌────────▼──────────────────────────────────▼─────────┐  │
+│  │           Shared State & Storage                    │  │
+│  │  ┌──────────────┐  ┌──────────────┐                │  │
+│  │  │  Repository  │  │  Event Store │                │  │
+│  │  │  Manager     │  │  (LMDB/NDB)  │                │  │
+│  │  └──────────────┘  └──────────────┘                │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │            Git Protocol Handler                      │  │
+│  │                                                      │  │
+│  │  1. Receive git-receive-pack request                │  │
+│  │  2. Parse ref updates from request                  │  │
+│  │  3. Query Nostr relay for state event               │  │
+│  │  4. Validate refs against state                     │  │
+│  │  5. If valid: spawn git-receive-pack                │  │
+│  │  6. If invalid: return HTTP error                   │  │
+│  │                                                      │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+         │                                      │
+         │ HTTP/Git                             │ WebSocket/Nostr
+         ▼                                      ▼
+    Git Clients                            Nostr Clients
+```
+
+## Component Design
+
+### 1. Main Server (`src/main.rs`)
+
+**Responsibilities:**
+- Initialize configuration from environment
+- Set up actix-web HTTP server
+- Initialize Nostr relay builder
+- Set up shared storage
+- Configure routes for both Git and Nostr endpoints
+- Handle graceful shutdown
+
+**Key Dependencies:**
+```rust
+actix-web = "4"
+tokio = { version = "1", features = ["full"] }
+nostr-relay-builder = "0.43"
+nostr-sdk = "0.43"
+```
+
+### 2. Git Module (`src/git/`)
+
+#### `handler.rs` - Git HTTP Handlers
+
+Implements actix-web handlers for Git Smart HTTP protocol:
+
+```rust
+// GET /<npub>/<identifier>.git/info/refs?service=git-upload-pack
+async fn info_refs_upload_pack(
+    req: HttpRequest,
+    state: web::Data<AppState>,
+) -> Result<HttpResponse>
+
+// POST /<npub>/<identifier>.git/git-upload-pack
+async fn git_upload_pack(
+    req: HttpRequest,
+    body: web::Payload,
+    state: web::Data<AppState>,
+) -> Result<HttpResponse>
+
+// GET /<npub>/<identifier>.git/info/refs?service=git-receive-pack
+async fn info_refs_receive_pack(
+    req: HttpRequest,
+    state: web::Data<AppState>,
+) -> Result<HttpResponse>
+
+// POST /<npub>/<identifier>.git/git-receive-pack
+// THIS IS WHERE THE MAGIC HAPPENS
+async fn git_receive_pack(
+    req: HttpRequest,
+    body: web::Payload,
+    state: web::Data<AppState>,
+) -> Result<HttpResponse>
+```
+
+#### `authorization.rs` - Push Validation
+
+**Core Logic:**
+
+```rust
+pub struct PushValidator {
+    nostr_client: Arc<Client>,
+    relay_url: String,
+}
+
+impl PushValidator {
+    /// Validate a push operation against Nostr state
+    pub async fn validate_push(
+        &self,
+        npub: &str,
+        identifier: &str,
+        ref_updates: Vec<RefUpdate>,
+    ) -> Result<ValidationResult> {
+        // 1. Fetch announcement and state events from local relay
+        let events = self.fetch_events(identifier).await?;
+        
+        // 2. Extract pubkey from npub
+        let pubkey = decode_npub(npub)?;
+        
+        // 3. Get recursive maintainer set
+        let maintainers = get_maintainers(&events, &pubkey, identifier);
+        
+        // 4. Get latest state from maintainers
+        let state = get_state_from_maintainers(&events, &maintainers)?;
+        
+        // 5. Validate each ref update
+        for ref_update in ref_updates {
+            if ref_update.ref_name.starts_with("refs/nostr/") {
+                // Allow refs/nostr/<event-id> for PRs
+                validate_pr_ref(&ref_update)?;
+            } else if ref_update.ref_name.starts_with("refs/heads/pr/") {
+                // Reject pr/* branches - should use refs/nostr/
+                return Err(Error::InvalidRef("pr/* branches must use refs/nostr/"));
+            } else {
+                // Validate against state event
+                validate_state_ref(&state, &ref_update)?;
+            }
+        }
+        
+        Ok(ValidationResult::Accept)
+    }
+}
+```
+
+**Key Functions:**
+
+```rust
+/// Parse ref updates from git-receive-pack request body
+fn parse_ref_updates(body: &[u8]) -> Result<Vec<RefUpdate>>
+
+/// Recursively find all maintainers
+fn get_maintainers(
+    events: &[Event],
+    pubkey: &str,
+    identifier: &str,
+) -> Vec<String>
+
+/// Get latest state from maintainer set
+fn get_state_from_maintainers(
+    events: &[Event],
+    maintainers: &[String],
+) -> Result<RepositoryState>
+
+/// Validate a ref matches the state event
+fn validate_state_ref(
+    state: &RepositoryState,
+    ref_update: &RefUpdate,
+) -> Result<()>
+```
+
+### 3. Nostr Module (`src/nostr/`)
+
+#### `relay.rs` - Relay Configuration
+
+```rust
+pub async fn build_relay(config: &Config) -> Result<LocalRelay> {
+    let builder = RelayBuilder::default()
+        .write_policy(RepositoryAnnouncementPolicy::new(config.domain.clone()))
+        .write_policy(RelatedEventsPolicy::new())
+        .query_policy(StandardQueryPolicy::new())
+        .on_event_saved(create_repository_hook(config.git_data_path.clone()));
+    
+    // Configure storage backend (LMDB or NDB)
+    let relay = LocalRelay::run(builder).await?;
+    
+    Ok(relay)
+}
+```
+
+#### `events.rs` - Event Handlers
+
+```rust
+/// Hook called when events are saved
+pub fn create_repository_hook(
+    git_data_path: PathBuf,
+) -> impl Fn(&Event) -> BoxFuture<'static, ()> {
+    move |event: &Event| {
+        let git_path = git_data_path.clone();
+        Box::pin(async move {
+            if event.kind == Kind::RepositoryAnnouncement {
+                handle_repository_announcement(event, &git_path).await;
+            } else if event.kind == Kind::RepositoryState {
+                handle_repository_state(event, &git_path).await;
+            }
+        })
+    }
+}
+
+async fn handle_repository_announcement(event: &Event, git_path: &Path) {
+    // 1. Parse repository from event
+    // 2. Check if listed in clone and relays tags
+    // 3. Create empty bare Git repository
+    // 4. Configure uploadpack.allowTipSHA1InWant
+    // 5. Configure uploadpack.allowUnreachable
+    // 6. Configure http.receivepack
+}
+
+async fn handle_repository_state(event: &Event, git_path: &Path) {
+    // 1. Parse state from event
+    // 2. Update repository HEAD if needed
+    // 3. Trigger proactive sync (GRASP-02)
+}
+```
+
+**Write Policies:**
+
+```rust
+/// Accept repository announcements that list this instance
+pub struct RepositoryAnnouncementPolicy {
+    domain: String,
+}
+
+impl WritePolicy for RepositoryAnnouncementPolicy {
+    fn admit_event(&self, event: &Event, _addr: &SocketAddr) 
+        -> BoxFuture<PolicyResult> 
+    {
+        Box::pin(async move {
+            if event.kind != Kind::RepositoryAnnouncement {
+                return PolicyResult::Accept; // Not our concern
+            }
+            
+            // Check if this instance is in clone and relays tags
+            let has_clone = event.tags.iter()
+                .any(|t| t.kind() == "clone" && t.content() == Some(&self.domain));
+            let has_relay = event.tags.iter()
+                .any(|t| t.kind() == "relays" && t.content() == Some(&self.domain));
+            
+            if has_clone && has_relay {
+                PolicyResult::Accept
+            } else {
+                PolicyResult::Reject("instance not listed in clone and relays".into())
+            }
+        })
+    }
+}
+
+/// Accept events related to stored announcements/issues/patches
+pub struct RelatedEventsPolicy;
+
+impl WritePolicy for RelatedEventsPolicy {
+    fn admit_event(&self, event: &Event, _addr: &SocketAddr) 
+        -> BoxFuture<PolicyResult> 
+    {
+        // Accept if event tags or is tagged by stored events
+        // Implementation requires querying the event store
+    }
+}
+```
+
+### 4. Storage Module (`src/storage/`)
+
+#### `repository.rs` - Repository Management
+
+```rust
+pub struct RepositoryManager {
+    git_data_path: PathBuf,
+}
+
+impl RepositoryManager {
+    /// Create a new bare Git repository
+    pub async fn create_repository(
+        &self,
+        npub: &str,
+        identifier: &str,
+    ) -> Result<PathBuf> {
+        let repo_path = self.git_data_path
+            .join(npub)
+            .join(format!("{}.git", identifier));
+        
+        // Create directory
+        tokio::fs::create_dir_all(&repo_path).await?;
+        
+        // Initialize bare repo
+        Command::new("git")
+            .args(&["init", "--bare"])
+            .arg(&repo_path)
+            .output()
+            .await?;
+        
+        // Configure
+        self.configure_repository(&repo_path).await?;
+        
+        Ok(repo_path)
+    }
+    
+    async fn configure_repository(&self, repo_path: &Path) -> Result<()> {
+        // Enable unauthenticated push (we handle auth ourselves)
+        git_config(repo_path, "http.receivepack", "true").await?;
+        
+        // Enable tip SHA1 fetching (required for ngit)
+        git_config(repo_path, "uploadpack.allowTipSHA1InWant", "true").await?;
+        
+        // Enable unreachable object fetching
+        git_config(repo_path, "uploadpack.allowUnreachable", "true").await?;
+        
+        Ok(())
+    }
+    
+    /// Check if repository exists
+    pub async fn repository_exists(
+        &self,
+        npub: &str,
+        identifier: &str,
+    ) -> bool {
+        let repo_path = self.git_data_path
+            .join(npub)
+            .join(format!("{}.git", identifier));
+        
+        repo_path.join("HEAD").exists() && 
+        repo_path.join("config").exists()
+    }
+}
+```
+
+### 5. Configuration (`src/config.rs`)
+
+```rust
+pub struct Config {
+    pub domain: String,
+    pub owner_npub: String,
+    pub relay_name: String,
+    pub relay_description: String,
+    pub git_data_path: PathBuf,
+    pub relay_data_path: PathBuf,
+    pub bind_address: SocketAddr,
+    pub log_level: String,
+}
+
+impl Config {
+    pub fn from_env() -> Result<Self> {
+        Ok(Config {
+            domain: env::var("NGIT_DOMAIN")?,
+            owner_npub: env::var("NGIT_OWNER_NPUB")?,
+            relay_name: env::var("NGIT_RELAY_NAME")?,
+            relay_description: env::var("NGIT_RELAY_DESCRIPTION")?,
+            git_data_path: PathBuf::from(
+                env::var("NGIT_GIT_DATA_PATH")
+                    .unwrap_or_else(|_| "./data/git".to_string())
+            ),
+            relay_data_path: PathBuf::from(
+                env::var("NGIT_RELAY_DATA_PATH")
+                    .unwrap_or_else(|_| "./data/relay".to_string())
+            ),
+            bind_address: env::var("NGIT_BIND_ADDRESS")
+                .unwrap_or_else(|_| "127.0.0.1:8080".to_string())
+                .parse()?,
+            log_level: env::var("RUST_LOG")
+                .unwrap_or_else(|_| "info".to_string()),
+        })
+    }
+}
+```
+
+## Data Flow
+
+### Push Operation Flow
+
+```
+1. Git Client → POST /<npub>/<id>.git/git-receive-pack
+                ↓
+2. git_receive_pack handler receives request
+                ↓
+3. Parse ref updates from request body
+                ↓
+4. Extract npub and identifier from URL
+                ↓
+5. PushValidator::validate_push()
+   ├─ Fetch events from local Nostr relay
+   ├─ Get maintainers recursively
+   ├─ Get latest state from maintainers
+   └─ Validate each ref update
+                ↓
+6. If VALID:
+   ├─ Spawn git-receive-pack subprocess
+   ├─ Stream request body to git stdin
+   └─ Stream git stdout back to client
+                ↓
+7. If INVALID:
+   └─ Return HTTP 403 with error message
+```
+
+### Repository Announcement Flow
+
+```
+1. Nostr Client → EVENT (Kind 30317)
+                ↓
+2. Nostr relay receives event
+                ↓
+3. RepositoryAnnouncementPolicy::admit_event()
+   ├─ Check if instance in clone tags
+   ├─ Check if instance in relays tags
+   └─ Accept or reject
+                ↓
+4. If ACCEPTED:
+   ├─ Event saved to store
+   └─ on_event_saved hook triggered
+                ↓
+5. handle_repository_announcement()
+   ├─ Parse repository details
+   ├─ Create Git repository directory
+   ├─ Initialize bare Git repo
+   └─ Configure Git settings
+```
+
+## Key Implementation Details
+
+### 1. Parsing Git Receive-Pack Protocol
+
+The Git receive-pack protocol uses a pkt-line format. We need to parse:
+
+```
+0000-0000-0000-0000 0000-0000-0000-0000 refs/heads/main\0 report-status
+0000-0000-0000-0000 0000-0000-0000-0000 refs/heads/dev
+```
+
+Each line has:
+- Old SHA (40 hex chars)
+- Space
+- New SHA (40 hex chars)
+- Space
+- Ref name
+- Optional capabilities (first line only, after \0)
+
+```rust
+pub struct RefUpdate {
+    pub old_sha: String,
+    pub new_sha: String,
+    pub ref_name: String,
+}
+
+pub fn parse_ref_updates(body: &[u8]) -> Result<Vec<RefUpdate>> {
+    // Parse pkt-line format
+    // Extract ref updates
+    // Return structured data
+}
+```
+
+### 2. Maintainer Recursion
+
+The maintainer resolution must handle cycles and correctly build the set:
+
+```rust
+fn get_maintainers_recursive(
+    events: &[Event],
+    pubkey: &str,
+    identifier: &str,
+    visited: &mut HashSet<String>,
+) -> HashSet<String> {
+    if visited.contains(pubkey) {
+        return HashSet::new();
+    }
+    
+    visited.insert(pubkey.to_string());
+    
+    let announcement = find_announcement(events, pubkey, identifier);
+    if announcement.is_none() {
+        return HashSet::new();
+    }
+    
+    let repo = parse_repository(announcement.unwrap());
+    
+    for maintainer in repo.maintainers {
+        get_maintainers_recursive(events, &maintainer, identifier, visited);
+    }
+    
+    visited.clone()
+}
+```
+
+### 3. State Event Validation
+
+```rust
+fn validate_state_ref(
+    state: &RepositoryState,
+    ref_update: &RefUpdate,
+) -> Result<()> {
+    if ref_update.ref_name.starts_with("refs/heads/") {
+        let branch_name = &ref_update.ref_name[11..];
+        if let Some(commit) = state.branches.get(branch_name) {
+            if commit == &ref_update.new_sha {
+                return Ok(());
+            }
+            return Err(Error::StateMismatch {
+                ref_name: ref_update.ref_name.clone(),
+                expected: commit.clone(),
+                got: ref_update.new_sha.clone(),
+            });
+        }
+        return Err(Error::RefNotInState(ref_update.ref_name.clone()));
+    }
+    
+    if ref_update.ref_name.starts_with("refs/tags/") {
+        let tag_name = &ref_update.ref_name[10..];
+        if let Some(commit) = state.tags.get(tag_name) {
+            if commit == &ref_update.new_sha {
+                return Ok(());
+            }
+            return Err(Error::StateMismatch {
+                ref_name: ref_update.ref_name.clone(),
+                expected: commit.clone(),
+                got: ref_update.new_sha.clone(),
+            });
+        }
+        return Err(Error::RefNotInState(ref_update.ref_name.clone()));
+    }
+    
+    Err(Error::InvalidRef(ref_update.ref_name.clone()))
+}
+```
+
+### 4. CORS Support
+
+As per GRASP-01, we must support CORS:
+
+```rust
+use actix_cors::Cors;
+
+fn configure_cors() -> Cors {
+    Cors::default()
+        .allow_any_origin()
+        .allowed_methods(vec!["GET", "POST", "OPTIONS"])
+        .allowed_headers(vec!["Content-Type"])
+        .max_age(3600)
+}
+
+// In main.rs
+App::new()
+    .wrap(configure_cors())
+    .configure(git_routes)
+    .configure(nostr_routes)
+```
+
+## Testing Strategy
+
+See [TEST_STRATEGY.md](TEST_STRATEGY.md) for comprehensive testing documentation, including:
+
+- **GRASP Compliance Testing Tool**: Reusable test suite that validates any GRASP implementation against the spec
+- **Spec-Mirrored Tests**: Test structure matches GRASP protocol documents exactly
+- **Clear Failure Messages**: Test failures cite exact spec lines (e.g., "GRASP-01:12-13")
+- **Multiple Test Levels**: Unit, integration, compliance, and end-to-end tests
+
+### Quick Overview
+
+```rust
+// Unit Tests - Individual functions
+#[test]
+fn test_parse_ref_updates() {
+    let body = b"0000... 0000... refs/heads/main\0report-status\n";
+    let updates = parse_ref_updates(body).unwrap();
+    assert_eq!(updates.len(), 1);
+    assert_eq!(updates[0].ref_name, "refs/heads/main");
+}
+
+// Integration Tests - Component interaction
+#[tokio::test]
+async fn test_full_push_flow() {
+    let app = test_app().await;
+    let (announcement, state) = app.create_repo_with_state()
+        .branch("main", "commit-123")
+        .build()
+        .await;
+    
+    let result = app.git_push("main", "commit-123").await;
+    assert!(result.success);
+}
+
+// Compliance Tests - GRASP spec validation
+#[tokio::test]
+async fn test_grasp_01_compliance() {
+    use grasp_compliance_tests::{TestContext, Grasp01Spec};
+    
+    let ctx = TestContext::builder()
+        .base_url(&server.url())
+        .build();
+    
+    let results = Grasp01Spec::test_compliance(&ctx).await;
+    assert!(results.all_passed(), "{}", results.report());
+}
+```
+
+The compliance testing tool is designed as a **standalone crate** that can be:
+- Used by ngit-grasp for self-validation
+- Published for other GRASP implementations to use
+- Updated as new GRASP specs are released
+- Run in CI/CD for continuous compliance verification
+
+## Performance Considerations
+
+### 1. Async All The Way
+
+- Use `tokio` for all I/O
+- Non-blocking Git subprocess spawning
+- Stream large pack files without buffering
+
+### 2. Connection Pooling
+
+- Reuse Nostr relay connections
+- Connection pool for internal relay queries
+
+### 3. Caching
+
+- Cache parsed state events (with TTL)
+- Cache maintainer sets
+- Invalidate on new state events
+
+```rust
+pub struct StateCache {
+    cache: Arc<RwLock<HashMap<String, CachedState>>>,
+}
+
+struct CachedState {
+    state: RepositoryState,
+    maintainers: Vec<String>,
+    timestamp: Instant,
+}
+
+impl StateCache {
+    pub async fn get_or_fetch(
+        &self,
+        identifier: &str,
+        fetcher: impl Future<Output = Result<(RepositoryState, Vec<String>)>>,
+    ) -> Result<(RepositoryState, Vec<String>)> {
+        // Check cache
+        // Return if fresh
+        // Otherwise fetch and cache
+    }
+}
+```
+
+## Future Extensions
+
+### GRASP-02: Proactive Sync
+
+Add background tasks:
+
+```rust
+pub struct ProactiveSyncTask {
+    relay_client: Client,
+    git_manager: RepositoryManager,
+}
+
+impl ProactiveSyncTask {
+    pub async fn run(&self) {
+        loop {
+            tokio::time::sleep(Duration::from_secs(3600)).await;
+            
+            // Fetch all announcements from our relay
+            let announcements = self.fetch_announcements().await;
+            
+            for ann in announcements {
+                // Sync events from listed relays
+                self.sync_events(&ann).await;
+                
+                // Sync git data from listed clones
+                self.sync_git_data(&ann).await;
+                
+                // Fetch PR data
+                self.sync_pr_data(&ann).await;
+            }
+        }
+    }
+}
+```
+
+### GRASP-05: Archive
+
+Relax the policy:
+
+```rust
+pub struct ArchiveAnnouncementPolicy;
+
+impl WritePolicy for ArchiveAnnouncementPolicy {
+    fn admit_event(&self, event: &Event, _addr: &SocketAddr) 
+        -> BoxFuture<PolicyResult> 
+    {
+        // Accept all repository announcements
+        // Don't check clone/relays tags
+        PolicyResult::Accept
+    }
+}
+```
+
+## Deployment
+
+### Single Binary
+
+```bash
+cargo build --release
+./target/release/ngit-grasp
+```
+
+### Docker
+
+```dockerfile
+FROM rust:1.75 as builder
+WORKDIR /app
+COPY . .
+RUN cargo build --release
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /app/target/release/ngit-grasp /usr/local/bin/
+EXPOSE 8080
+CMD ["ngit-grasp"]
+```
+
+### Systemd
+
+```ini
+[Unit]
+Description=ngit-grasp GRASP server
+After=network.target
+
+[Service]
+Type=simple
+User=git
+WorkingDirectory=/opt/ngit-grasp
+EnvironmentFile=/opt/ngit-grasp/.env
+ExecStart=/usr/local/bin/ngit-grasp
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Security Considerations
+
+1. **Input Validation**: All npub/identifier inputs must be validated
+2. **Path Traversal**: Prevent directory traversal in repository paths
+3. **DoS Protection**: Rate limiting on both HTTP and WebSocket
+4. **Resource Limits**: Limit pack file sizes, event sizes
+5. **Nostr Event Validation**: Strict signature verification
+
+## Conclusion
+
+The inline authorization approach provides a cleaner, more maintainable architecture than hook-based authorization while maintaining full GRASP-01 compliance. The Rust ecosystem provides excellent libraries for both Git and Nostr protocols, enabling a high-performance, type-safe implementation.
+
+The key insight is that we don't need to rely on Git's hook mechanism when we have full control over the HTTP layer that Git operates through. By intercepting at the HTTP handler level, we gain better error handling, easier testing, and tighter integration between the Git and Nostr components.
diff --git a/docs/explanation/comparison.md b/docs/explanation/comparison.md
new file mode 100644
index 0000000..be16f9e
--- /dev/null
+++ b/docs/explanation/comparison.md
@@ -0,0 +1,256 @@
+# ngit-grasp vs ngit-relay Comparison
+
+## High-Level Comparison
+
+| Aspect | ngit-relay (Reference) | ngit-grasp (This Project) |
+|--------|------------------------|---------------------------|
+| **Language** | Go | Rust |
+| **Architecture** | Multi-process (nginx, git-http-backend, hooks, relay) | Single integrated process |
+| **Authorization** | Git pre-receive hook | Inline HTTP handler |
+| **Packaging** | Docker + supervisord | Single binary or Docker |
+| **Configuration** | Multiple config files | Environment variables |
+| **Deployment** | Docker Compose | Binary or Docker |
+| **Testing** | Go tests + shell scripts | Rust unit + integration tests |
+
+## Component Breakdown
+
+### ngit-relay (Go)
+
+```
+┌─────────────────────────────────────────────────┐
+│                   Docker Container               │
+├─────────────────────────────────────────────────┤
+│                                                  │
+│  ┌──────────┐         ┌─────────────────────┐  │
+│  │  nginx   │────────▶│ git-http-backend    │  │
+│  │  :80     │         │ (C binary)          │  │
+│  └──────────┘         └──────────┬──────────┘  │
+│       │                           │              │
+│       │                           ▼              │
+│       │                  ┌─────────────────┐    │
+│       │                  │  Git Repo       │    │
+│       │                  │  + Hooks        │    │
+│       │                  └────────┬────────┘    │
+│       │                           │              │
+│       │                           ▼              │
+│       │                  ┌─────────────────┐    │
+│       │                  │ pre-receive     │    │
+│       │                  │ (Go binary)     │    │
+│       │                  └────────┬────────┘    │
+│       │                           │              │
+│       │                           │ WebSocket    │
+│       │                           ▼              │
+│       │                  ┌─────────────────┐    │
+│       └─────────────────▶│  Khatru Relay   │    │
+│                          │  (Go)           │    │
+│                          └─────────────────┘    │
+│                                                  │
+│  ┌──────────────────────────────────────────┐  │
+│  │         supervisord                       │  │
+│  │  - nginx                                  │  │
+│  │  - khatru                                 │  │
+│  │  - proactive-sync                         │  │
+│  └──────────────────────────────────────────┘  │
+│                                                  │
+└─────────────────────────────────────────────────┘
+```
+
+### ngit-grasp (Rust)
+
+```
+┌─────────────────────────────────────────────────┐
+│              ngit-grasp (Single Binary)          │
+├─────────────────────────────────────────────────┤
+│                                                  │
+│  ┌──────────────────────────────────────────┐  │
+│  │         actix-web HTTP Server             │  │
+│  │              :8080                        │  │
+│  └───────┬──────────────────────┬────────────┘  │
+│          │                      │                │
+│          ▼                      ▼                │
+│  ┌──────────────┐      ┌──────────────────┐    │
+│  │ Git Handlers │      │  Nostr Relay     │    │
+│  │              │      │  (relay-builder) │    │
+│  │ - upload-pk  │      │                  │    │
+│  │ - receive-pk │◀─────│  - Policies      │    │
+│  │   + inline   │ query│  - Event store   │    │
+│  │   validation │      │  - WebSocket     │    │
+│  └──────┬───────┘      └──────────────────┘    │
+│         │                                        │
+│         ▼                                        │
+│  ┌──────────────┐                               │
+│  │  Git Repos   │                               │
+│  │  (spawned    │                               │
+│  │   git cmds)  │                               │
+│  └──────────────┘                               │
+│                                                  │
+│  ┌──────────────────────────────────────────┐  │
+│  │      Shared State (Arc<AppState>)         │  │
+│  │  - RepositoryManager                      │  │
+│  │  - NostrClient                            │  │
+│  │  - StateCache                             │  │
+│  └──────────────────────────────────────────┘  │
+│                                                  │
+└─────────────────────────────────────────────────┘
+```
+
+## Detailed Feature Comparison
+
+### Git Protocol Handling
+
+| Feature | ngit-relay | ngit-grasp |
+|---------|-----------|-----------|
+| Implementation | git-http-backend (C) | git-http-backend (Rust crate) |
+| Process model | nginx → C binary | actix-web → Rust handler |
+| Upload pack | Passthrough | Passthrough with validation |
+| Receive pack | Hook-based auth | Inline validation |
+| Error handling | Hook stderr | HTTP response |
+| CORS | nginx config | actix-cors middleware |
+
+### Nostr Relay
+
+| Feature | ngit-relay | ngit-grasp |
+|---------|-----------|-----------|
+| Implementation | Khatru (Go) | nostr-relay-builder (Rust) |
+| Event store | Badger (Go) | LMDB or NDB (Rust) |
+| Policies | Go functions | Rust traits |
+| WebSocket | Khatru built-in | nostr-relay-builder |
+| NIP-11 | Manual JSON | Built-in support |
+
+### Authorization Logic
+
+| Feature | ngit-relay | ngit-grasp |
+|---------|-----------|-----------|
+| Location | pre-receive hook | HTTP handler |
+| Language | Go | Rust |
+| State query | WebSocket to localhost:3334 | In-process function call |
+| Error reporting | stderr → git client | HTTP response body |
+| Ref validation | Line-by-line stdin | Parsed from request body |
+| Maintainer resolution | Recursive Go function | Recursive Rust function |
+| State caching | Per-request | Shared cache with TTL |
+
+### Repository Management
+
+| Feature | ngit-relay | ngit-grasp |
+|---------|-----------|-----------|
+| Creation | Event hook + shell commands | Event hook + tokio::process |
+| Configuration | git config via shell | git config via tokio::process |
+| Hook installation | Symlinks | Not needed (inline auth) |
+| Permissions | chown nginx:nginx | tokio::fs permissions |
+| Path structure | `<npub>/<id>.git` | `<npub>/<id>.git` (same) |
+
+### Deployment
+
+| Feature | ngit-relay | ngit-grasp |
+|---------|-----------|-----------|
+| Dependencies | nginx, git, Go runtime | git, Rust binary (no runtime) |
+| Process management | supervisord | Single process (tokio) |
+| Configuration | Multiple files + .env | .env only |
+| Docker image size | ~500MB (Alpine + tools) | ~50MB (scratch + binary + git) |
+| Startup time | ~2-5 seconds | ~0.5 seconds |
+| Memory usage | ~100-200MB (multiple processes) | ~50-100MB (single process) |
+
+### Development Experience
+
+| Feature | ngit-relay | ngit-grasp |
+|---------|-----------|-----------|
+| Build time | Fast (Go) | Medium (Rust first build, then fast) |
+| Type safety | Go (good) | Rust (excellent) |
+| Testing | Go test + shell | Rust test (unit + integration) |
+| Debugging | Multiple processes | Single process |
+| Hot reload | Manual | cargo-watch |
+| IDE support | Good (Go) | Excellent (rust-analyzer) |
+
+## Performance Comparison (Estimated)
+
+| Metric | ngit-relay | ngit-grasp | Notes |
+|--------|-----------|-----------|-------|
+| Startup | ~2-5s | ~0.5s | Fewer processes |
+| Memory | ~150MB | ~75MB | Single process, no GC |
+| CPU (idle) | ~1-2% | ~0.5% | Fewer processes |
+| Push latency | +50-100ms | +10-20ms | No hook spawn overhead |
+| Clone latency | ~same | ~same | Both passthrough to Git |
+| Concurrent pushes | Good | Excellent | Tokio async vs goroutines |
+| Event ingestion | Good | Excellent | Rust async + zero-copy |
+
+*Note: These are estimates. Actual performance depends on workload and hardware.*
+
+## Code Complexity
+
+### Lines of Code (Estimated)
+
+| Component | ngit-relay | ngit-grasp |
+|-----------|-----------|-----------|
+| Main server | ~150 | ~200 |
+| Git handlers | ~0 (C binary) | ~500 |
+| Auth logic | ~200 | ~300 |
+| Nostr relay | ~500 | ~100 (using library) |
+| Shared utils | ~300 | ~200 |
+| Config/setup | ~200 | ~100 |
+| **Total** | **~1,350** | **~1,400** |
+
+Similar complexity, but ngit-grasp has:
+- More Git protocol code (we implement it)
+- Less Nostr relay code (using library)
+- Less deployment code (no hooks/supervisord)
+
+## Migration Path
+
+For users of ngit-relay, migration to ngit-grasp would involve:
+
+1. **Export data** from Badger to LMDB/NDB
+2. **Copy Git repositories** (same structure)
+3. **Update environment variables** (mostly compatible)
+4. **Change deployment** from Docker Compose to binary/Docker
+5. **Update URLs** if domain changes
+
+The **Nostr events** and **Git data** are compatible - only the server changes.
+
+## When to Choose Each
+
+### Choose ngit-relay (Reference) if:
+
+- ✅ You need a proven, production-tested implementation
+- ✅ You're already familiar with Go
+- ✅ You want to stay close to the reference
+- ✅ You need to deploy immediately
+- ✅ You prefer Docker Compose workflows
+
+### Choose ngit-grasp (This Project) if:
+
+- ✅ You want better performance and lower resource usage
+- ✅ You prefer Rust's type safety and ecosystem
+- ✅ You want simpler deployment (single binary)
+- ✅ You want to contribute to a modern codebase
+- ✅ You're building on top of the GRASP protocol
+- ✅ You want inline authorization over hooks
+- ✅ You need better integration testing
+
+## Future Roadmap Comparison
+
+### ngit-relay (Reference)
+- ✅ GRASP-01 complete
+- 🔄 GRASP-02 in progress
+- ⏭️ GRASP-05 planned
+- ⏭️ NIP-42 auth-to-read
+- ⏭️ NIP-70 protected events
+- ⏭️ Spam prevention
+
+### ngit-grasp (This Project)
+- 🔄 GRASP-01 in development
+- ⏭️ GRASP-02 planned (easier with Rust async)
+- ⏭️ GRASP-05 planned
+- ⏭️ Advanced caching strategies
+- ⏭️ Metrics and observability
+- ⏭️ Plugin system for custom policies
+
+## Conclusion
+
+Both implementations are valid approaches to GRASP:
+
+- **ngit-relay** is the mature, proven reference implementation
+- **ngit-grasp** is a modern, performant alternative with better DX
+
+The choice depends on your priorities: stability vs. performance, familiarity vs. innovation, proven vs. cutting-edge.
+
+For new deployments where performance and simplicity matter, **ngit-grasp** is the recommended choice. For production systems requiring maximum stability, **ngit-relay** is the safer bet until ngit-grasp reaches maturity.
diff --git a/docs/explanation/decisions.md b/docs/explanation/decisions.md
new file mode 100644
index 0000000..e9b7422
--- /dev/null
+++ b/docs/explanation/decisions.md
@@ -0,0 +1,174 @@
+# Architecture Decision Summary
+
+## Question: Pre-receive Hook vs. Inline Authorization?
+
+After investigating the `git-http-backend` Rust crate and the reference implementation, we have determined that **inline authorization is both pragmatic and superior**.
+
+## Investigation Findings
+
+### git-http-backend Crate Analysis
+
+The `git-http-backend` crate (v0.1.3) provides:
+
+1. **Low-level Git protocol handling** via actix-web handlers
+2. **Process spawning** of `git-receive-pack` and `git-upload-pack`
+3. **Stream-based I/O** between HTTP and Git processes
+4. **Flexible path rewriting** through the `GitConfig` trait
+
+**Key Finding**: The crate spawns Git as a subprocess in `git_receive_pack.rs`. We can intercept **before** this spawn happens.
+
+### Reference Implementation (ngit-relay) Analysis
+
+The Go-based reference uses:
+
+1. **nginx** as HTTP frontend
+2. **git-http-backend** (C binary) for Git protocol
+3. **Pre-receive hook** (Go binary) for authorization
+4. **Khatru** (Go) for Nostr relay
+5. **supervisord** for process management
+6. **Docker** for packaging
+
+The pre-receive hook:
+- Reads ref updates from stdin
+- Queries local Nostr relay via WebSocket
+- Validates each ref against state events
+- Exits with 0 (accept) or 1 (reject)
+- Errors printed to stderr appear as `remote:` messages in git client
+
+## Decision: Inline Authorization ✅
+
+### Why This Is Pragmatic
+
+1. **The crate supports it**: We can implement a custom `git_receive_pack` handler that validates before spawning Git
+2. **Better error handling**: Direct HTTP responses vs. parsing hook stderr
+3. **Simpler deployment**: Single binary, no hook management
+4. **Easier testing**: Pure Rust unit tests, no shell scripts
+5. **Performance**: Avoid spawning Git for invalid pushes
+6. **Type safety**: Share types between Git and Nostr modules
+
+### Implementation Approach
+
+```rust
+// Instead of using git-http-backend's handler as-is:
+pub async fn git_receive_pack(
+    req: HttpRequest,
+    body: web::Payload,
+    state: web::Data<AppState>,
+) -> Result<HttpResponse> {
+    // 1. Parse repository path from URL
+    let (npub, identifier) = parse_repo_path(&req)?;
+    
+    // 2. Buffer enough of the request to parse ref updates
+    let ref_updates = parse_ref_updates(&body).await?;
+    
+    // 3. VALIDATE AGAINST NOSTR STATE
+    let validator = PushValidator::new(&state.nostr_client);
+    match validator.validate_push(&npub, &identifier, &ref_updates).await {
+        Ok(_) => {
+            // 4. Valid! Spawn git-receive-pack and stream
+            spawn_git_receive_pack(req, body, state).await
+        }
+        Err(e) => {
+            // 5. Invalid! Return HTTP error
+            Ok(HttpResponse::Forbidden()
+                .body(format!("Push rejected: {}", e)))
+        }
+    }
+}
+```
+
+### Advantages Over Hooks
+
+| Aspect | Pre-receive Hook | Inline Authorization |
+|--------|------------------|---------------------|
+| Error messages | Via stderr, prefixed with `remote:` | Direct HTTP response body |
+| Testing | Requires Git repo setup | Pure Rust unit tests |
+| Debugging | Hook logs separate from server | Unified logging |
+| Deployment | Symlinks, permissions, hook scripts | Single binary |
+| Performance | Always spawn Git | Skip Git for invalid pushes |
+| State sharing | IPC or network | Direct memory access |
+| Type safety | Separate binaries | Shared Rust types |
+
+### Potential Concerns & Mitigations
+
+**Concern**: "What if we need to validate the actual pack data, not just refs?"
+
+**Mitigation**: We can still do this inline! Parse the pack stream before forwarding to Git. The `git-http-backend` crate already buffers the request body.
+
+**Concern**: "Doesn't Git expect hooks for certain operations?"
+
+**Mitigation**: We're not eliminating hooks entirely. Post-receive hooks might still be useful for notifications. We're just moving *authorization* out of hooks.
+
+**Concern**: "What about compatibility with standard Git setups?"
+
+**Mitigation**: The Git Smart HTTP protocol is standardized. Our inline validation is transparent to clients. We're still using real Git repositories and spawning real `git-receive-pack`.
+
+## Comparison with Reference Implementation
+
+### Reference (ngit-relay)
+```
+Client → nginx → git-http-backend → Git → pre-receive hook → validate → accept/reject
+                                              ↓
+                                    Query Nostr relay (WebSocket)
+```
+
+### Our Approach (ngit-grasp)
+```
+Client → actix-web → validate → Git → accept
+                        ↓
+                Query Nostr relay (in-process)
+                        ↓
+                     reject ← return HTTP error
+```
+
+## Implementation Complexity
+
+### Hook-based (if we went that route)
+- ✅ Simpler: Follow reference implementation
+- ❌ More components: Hook binaries, symlinks
+- ❌ More complex testing: Need Git repos, shell scripts
+- ❌ More complex deployment: Hook installation, permissions
+
+### Inline (our choice)
+- ❌ More complex: Custom Git protocol handling
+- ✅ Fewer components: Single binary
+- ✅ Simpler testing: Pure Rust
+- ✅ Simpler deployment: Just run the binary
+
+**Verdict**: Slightly more complex initially, but much simpler long-term.
+
+## Code Reuse from Reference
+
+We can still reuse the **logic** from the reference implementation:
+
+- Maintainer recursion algorithm
+- State validation logic
+- Event filtering policies
+- Repository provisioning workflow
+
+We're just implementing it in Rust within our HTTP handlers rather than in Git hooks.
+
+## Conclusion
+
+**Inline authorization is both pragmatic and superior for a Rust implementation.**
+
+The `git-http-backend` crate provides sufficient flexibility through its handler architecture. By intercepting at the HTTP layer, we gain:
+
+1. Better error handling and user experience
+2. Simpler deployment and operations
+3. Easier testing and debugging
+4. Better performance characteristics
+5. Tighter integration between components
+
+The additional complexity of parsing the Git protocol is minimal compared to the benefits, and we're still using the standard Git binaries for the actual repository operations.
+
+## Next Steps
+
+1. ✅ Document architecture (this file + ARCHITECTURE.md)
+2. ⏭️ Set up project structure with Cargo workspace
+3. ⏭️ Implement core types (RefUpdate, RepositoryState, etc.)
+4. ⏭️ Implement Git protocol parsing
+5. ⏭️ Implement Nostr relay with policies
+6. ⏭️ Implement push validation logic
+7. ⏭️ Integration tests
+8. ⏭️ GRASP-01 compliance testing
diff --git a/docs/explanation/inline-authorization.md b/docs/explanation/inline-authorization.md
new file mode 100644
index 0000000..98f6e5a
--- /dev/null
+++ b/docs/explanation/inline-authorization.md
@@ -0,0 +1,403 @@
+# Explanation: Inline Authorization
+
+**Purpose:** Understand why ngit-grasp validates Git pushes inline rather than using Git hooks  
+**Audience:** Developers and architects wanting to understand design decisions
+
+---
+
+## The Problem
+
+Git hosting with authorization requires validating pushes before accepting them. The question is: **where** should this validation happen?
+
+Two approaches exist:
+
+1. **Git Hooks** (traditional): Use Git's pre-receive hook mechanism
+2. **Inline Authorization** (our approach): Validate before spawning Git
+
+This document explains why we chose inline authorization and what benefits it provides.
+
+---
+
+## Background: How Git Hooks Work
+
+Git provides a **pre-receive hook** that runs during `git push`:
+
+```
+Client              Server
+  |                   |
+  |--- git push ----->|
+  |                   |--- spawn git-receive-pack
+  |                   |
+  |                   |--- pre-receive hook runs
+  |                   |    (reads stdin: old new ref)
+  |                   |    (exit 0 = accept, 1 = reject)
+  |                   |
+  |<--- success ------| (if hook exits 0)
+  |<--- error --------| (if hook exits 1)
+```
+
+**Pros:**
+- Standard Git mechanism
+- Language-agnostic (hook can be any executable)
+- Well-documented
+
+**Cons:**
+- Hook output goes to stderr (client sees as `remote:` messages)
+- Hard to provide structured error messages
+- Requires hook installation and management
+- Difficult to test (needs Git repository setup)
+- Hook runs *after* Git has started processing
+
+---
+
+## Background: How Inline Authorization Works
+
+With inline authorization, we validate **before** spawning Git:
+
+```
+Client              Server (ngit-grasp)
+  |                   |
+  |--- git push ----->|--- HTTP handler receives request
+  |                   |
+  |                   |--- Parse ref updates from request
+  |                   |--- Query Nostr relay for state
+  |                   |--- Validate push against state
+  |                   |
+  |                   |--- If invalid: return HTTP error
+  |                   |--- If valid: spawn git-receive-pack
+  |                   |
+  |<--- success ------| (if valid)
+  |<--- HTTP error ---| (if invalid)
+```
+
+**Pros:**
+- Full control over error messages (HTTP response)
+- Can skip spawning Git entirely for invalid pushes
+- Easier testing (pure Rust, no Git setup needed)
+- Shared state between Git and Nostr components
+- Better performance (early rejection)
+
+**Cons:**
+- Requires parsing Git protocol ourselves
+- Less standard than hooks
+- Tighter coupling to Git HTTP protocol
+
+---
+
+## Why Inline Authorization Is Better for GRASP
+
+### 1. Better Error Messages
+
+**With hooks:**
+```
+$ git push
+remote: error: Push rejected - not authorized for ref refs/heads/main
+remote: See https://docs.gitnostr.com/errors/unauthorized
+To https://gitnostr.com/alice/myrepo.git
+ ! [remote rejected] main -> main (pre-receive hook declined)
+```
+
+**With inline authorization:**
+```
+$ git push
+error: RPC failed; HTTP 403 Forbidden
+error: {
+  "error": "unauthorized",
+  "ref": "refs/heads/main",
+  "required_state": "event_id_abc123",
+  "your_pubkey": "npub1alice...",
+  "docs": "https://docs.gitnostr.com/errors/unauthorized"
+}
+```
+
+The inline approach can return **structured JSON** with actionable information.
+
+### 2. Performance Benefits
+
+**With hooks:**
+- Git process spawns
+- Git starts receiving pack data
+- Hook runs (might query Nostr relay)
+- If rejected, Git throws away received data
+
+**With inline authorization:**
+- Parse ref updates from HTTP request
+- Validate against Nostr state (cached)
+- If rejected, return HTTP 403 immediately
+- Never spawn Git for invalid pushes
+
+**Result:** Faster rejection, less resource usage.
+
+### 3. Easier Testing
+
+**With hooks:**
+```bash
+# Test setup
+mkdir -p /tmp/test-repo
+cd /tmp/test-repo
+git init --bare
+cp pre-receive.sh hooks/pre-receive
+chmod +x hooks/pre-receive
+
+# Test execution
+git push /tmp/test-repo main
+
+# Cleanup
+rm -rf /tmp/test-repo
+```
+
+**With inline authorization:**
+```rust
+#[tokio::test]
+async fn test_unauthorized_push() {
+    let state = create_test_state().await;
+    let result = validate_push(&state, "refs/heads/main", alice_pubkey).await;
+    assert!(result.is_err());
+}
+```
+
+**Result:** Pure Rust unit tests, no shell scripts, no Git setup.
+
+### 4. Shared State and Types
+
+**With hooks:**
+- Hook is separate process
+- Must query Nostr relay over WebSocket
+- Can't share in-memory cache
+- Separate error types
+
+**With inline authorization:**
+```rust
+pub struct GitHandler {
+    nostr_relay: Arc<NostrRelay>,  // Shared!
+    state_cache: Arc<StateCache>,   // Shared!
+}
+
+impl GitHandler {
+    async fn validate_push(&self, refs: &[RefUpdate]) -> Result<()> {
+        // Direct access to Nostr state
+        let state = self.state_cache.get_latest().await?;
+        // Validate using shared types
+        state.validate_refs(refs)?;
+        Ok(())
+    }
+}
+```
+
+**Result:** Better performance, type safety, simpler architecture.
+
+### 5. Simpler Deployment
+
+**With hooks (ngit-relay):**
+```
+Docker container:
+  - nginx (HTTP frontend)
+  - git-http-backend (C binary)
+  - pre-receive hook (Go binary) 
+  - Khatru relay (Go binary)
+  - supervisord (process manager)
+  
+Setup steps:
+  1. Install all components
+  2. Configure nginx
+  3. Install hook in each repository
+  4. Set up supervisord
+  5. Configure inter-process communication
+```
+
+**With inline authorization (ngit-grasp):**
+```
+Single Rust binary:
+  - HTTP server (actix-web)
+  - Git protocol handler
+  - Nostr relay
+  - Authorization logic
+  
+Setup steps:
+  1. Run binary
+  2. Configure environment variables
+```
+
+**Result:** Simpler deployment, fewer moving parts.
+
+---
+
+## Technical Implementation
+
+### How We Parse Ref Updates
+
+The Git HTTP protocol sends ref updates in the request body:
+
+```
+POST /alice/myrepo.git/git-receive-pack HTTP/1.1
+Content-Type: application/x-git-receive-pack-request
+
+0000000000000000000000000000000000000000 abc123... refs/heads/main\0 report-status
+```
+
+We parse this **before** spawning Git:
+
+```rust
+pub async fn git_receive_pack(
+    req: HttpRequest,
+    body: web::Bytes,
+) -> Result<HttpResponse, Error> {
+    // 1. Parse ref updates from request body
+    let ref_updates = parse_ref_updates(&body)?;
+    
+    // 2. Validate against Nostr state
+    let state = get_latest_state(&repo).await?;
+    validate_push(&state, &ref_updates).await?;
+    
+    // 3. If valid, spawn git-receive-pack
+    spawn_git_receive_pack(req, body).await
+}
+```
+
+### How We Validate
+
+Validation checks:
+1. Does pusher's pubkey have write access?
+2. Are they listed as a maintainer in the latest state event?
+3. Do maintainer sets form a valid chain?
+
+```rust
+async fn validate_push(
+    state: &RepoState,
+    refs: &[RefUpdate],
+) -> Result<()> {
+    for ref_update in refs {
+        // Check if pusher is authorized for this ref
+        if !state.is_authorized(&ref_update.name, pusher_pubkey) {
+            return Err(Error::Unauthorized {
+                ref_name: ref_update.name.clone(),
+                pubkey: pusher_pubkey,
+            });
+        }
+    }
+    Ok(())
+}
+```
+
+---
+
+## Comparison with Reference Implementation
+
+| Aspect | ngit-relay (hooks) | ngit-grasp (inline) |
+|--------|-------------------|---------------------|
+| **Components** | nginx + git-http-backend + hook + Khatru | Single Rust binary |
+| **Validation** | Pre-receive hook (separate process) | Inline HTTP handler |
+| **Error messages** | Hook stderr → `remote:` | HTTP response JSON |
+| **Performance** | Spawns Git first | Validates first |
+| **Testing** | Shell scripts + Go tests | Pure Rust tests |
+| **Deployment** | Docker + supervisord | Single binary |
+| **State sharing** | WebSocket query | Direct memory access |
+
+Both are GRASP-compliant, but inline authorization is simpler and more efficient.
+
+---
+
+## Trade-offs and Limitations
+
+### What We Gain
+- ✅ Better error messages
+- ✅ Better performance
+- ✅ Easier testing
+- ✅ Simpler deployment
+- ✅ Tighter integration
+
+### What We Lose
+- ❌ Non-standard approach (not using Git's hook system)
+- ❌ Tighter coupling to Git HTTP protocol
+- ❌ Must parse protocol ourselves
+
+### Is It Worth It?
+
+**Yes**, because:
+1. The `git-http-backend` crate handles protocol parsing
+2. GRASP is already non-standard (Nostr authorization)
+3. Benefits far outweigh the coupling cost
+4. We can still add hook support later if needed
+
+---
+
+## Alternative Considered: Hybrid Approach
+
+We could use **both** inline validation and hooks:
+
+```rust
+// Inline: Fast path for common cases
+if !quick_validate(pusher).await? {
+    return Err(Error::Unauthorized);
+}
+
+// Hook: Detailed validation
+spawn_git_with_hook().await?;
+```
+
+**Why we didn't choose this:**
+- Added complexity
+- Redundant validation
+- Slower (two validation steps)
+- Harder to maintain
+
+If inline validation is sufficient, why add hooks?
+
+---
+
+## Future Considerations
+
+### If We Need Hooks Later
+
+We can add hook support without removing inline validation:
+
+```rust
+pub struct GitConfig {
+    inline_validation: bool,  // Default: true
+    hook_validation: bool,    // Default: false
+}
+```
+
+This would allow:
+- Migration path for hook-based systems
+- Extra validation for paranoid deployments
+- Compatibility with other Git tools
+
+### If Git Protocol Changes
+
+The `git-http-backend` crate abstracts protocol details. If the Git protocol changes:
+- Update the crate dependency
+- Adjust our ref parsing if needed
+- Tests will catch any breakage
+
+---
+
+## Conclusion
+
+**Inline authorization is the right choice for ngit-grasp** because:
+
+1. It provides better error messages for users
+2. It's more performant (early rejection)
+3. It's easier to test (pure Rust)
+4. It's simpler to deploy (single binary)
+5. It enables better integration (shared state)
+
+The trade-off (coupling to Git HTTP protocol) is acceptable because:
+- The protocol is stable and well-specified
+- The `git-http-backend` crate abstracts details
+- Benefits far outweigh the cost
+
+This decision aligns with our goal of creating a **developer-friendly, production-ready GRASP implementation**.
+
+---
+
+## Related Documentation
+
+- [Architecture Overview](architecture.md) - Full system design
+- [Design Decisions](decisions.md) - All architectural choices
+- [Comparison with ngit-relay](comparison.md) - Detailed comparison
+- [Git Protocol Reference](../reference/git-protocol.md) - Protocol details
+
+---
+
+*Part of the [ngit-grasp explanation docs](./)*