3 files changed, 88 insertions, 22 deletions

diff --git a/AGENTS.md b/AGENTS.md
index ed9c97d..ec1ec60 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,8 +33,8 @@ nix-shell --run "cargo build"
 **Integration tests require relay running:**
 
 ```bash
-# Start ngit-relay first (choose any available port, example uses 18081)
-docker run --rm -p 18081:8081 -e NGIT_BIND_ADDRESS=0.0.0.0:8081 ghcr.io/danconwaydev/ngit-relay:latest
+# Start ngit-relay first (use any available port to avoid conflicts)
+docker run --rm -p 18081:8081 ghcr.io/danconwaydev/ngit-relay:latest
 
 # From grasp-audit directory, set RELAY_URL to match your port
 RELAY_URL="ws://localhost:18081" nix develop -c cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture
@@ -42,6 +42,8 @@ RELAY_URL="ws://localhost:18081" nix develop -c cargo test --lib test_grasp01_no
 
 Tests marked `#[ignore]` need relay - unit tests don't.
 
+**Note:** Always use a random available port for the relay to avoid conflicts with existing services.
+
 ### Running Single Test
 
 ```bash
@@ -49,6 +51,32 @@ Tests marked `#[ignore]` need relay - unit tests don't.
 nix develop -c cargo test --lib specific_test_name -- --nocapture
 ```
 
+### Quick Test Verification
+
+To verify GRASP-01 compliance tests are working correctly:
+
+```bash
+cd grasp-audit && RELAY_URL="ws://localhost:18081" nix develop -c cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture 2>&1 | tail -60
+```
+
+**Expected Output:**
+- 2-3 tests passing
+- 15 tests showing "Not implemented yet"
+
+### Troubleshooting
+
+**Buffer Size Errors:**
+If you see mpsc channel buffer size panics on first test run, this is usually transient. Simply run the tests again.
+
+**Verify Relay is Running:**
+Check if relay is accessible before running tests:
+```bash
+nak req -l 1 ws://localhost:18081  # Replace port with your chosen port
+```
+
+**Port Conflicts:**
+Always use a random available port to avoid conflicts with existing services. If a port is busy, choose a different one for docker.
+
 ## Code Patterns
 
 ### nostr-sdk 0.43 Breaking Changes (vs 0.35)
@@ -133,6 +161,9 @@ cd grasp-audit && RELAY_URL="ws://localhost:18081" nix develop -c cargo test --i
 # Run single test
 cd grasp-audit && nix develop -c cargo test --lib test_name -- --nocapture
 
+# Verify GRASP-01 tests (cleaner output)
+cd grasp-audit && RELAY_URL="ws://localhost:18081" nix develop -c cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture 2>&1 | tail -60
+
 # Check session files
 ls work/  # Should only have README.md when clean
 ```
diff --git a/grasp-audit/src/client.rs b/grasp-audit/src/client.rs
index 4831d3f..b80b59f 100644
--- a/grasp-audit/src/client.rs
+++ b/grasp-audit/src/client.rs
@@ -24,11 +24,12 @@ impl AuditClient {
         
         // Wait for connection to establish (with retries)
         let mut attempts = 0;
+        let mut connected = false;
         while attempts < 20 {
             tokio::time::sleep(Duration::from_millis(100)).await;
             
             let relays = client.relays().await;
-            let connected = relays.values().any(|r| r.is_connected());
+            connected = relays.values().any(|r| r.is_connected());
             
             if connected {
                 break;
@@ -37,6 +38,25 @@ impl AuditClient {
             attempts += 1;
         }
         
+        // Verify we actually connected
+        if !connected {
+            return Err(anyhow!(
+                "Failed to connect to relay at '{}'\n\
+                \n\
+                Possible causes:\n\
+                  • Relay is not running at this address\n\
+                  • Network connectivity issues\n\
+                  • Incorrect URL or port\n\
+                \n\
+                To start ngit-relay for testing:\n\
+                  docker run --rm -p 18081:8081 ghcr.io/danconwaydev/ngit-relay:latest\n\
+                \n\
+                Or use the test script:\n\
+                  cd grasp-audit && ./test-ngit-relay.sh",
+                relay_url
+            ));
+        }
+        
         // Give it a bit more time to stabilize
         tokio::time::sleep(Duration::from_millis(200)).await;
         
diff --git a/grasp-audit/src/specs/grasp01_nostr_relay.rs b/grasp-audit/src/specs/grasp01_nostr_relay.rs
index 7c4ef1e..5a93672 100644
--- a/grasp-audit/src/specs/grasp01_nostr_relay.rs
+++ b/grasp-audit/src/specs/grasp01_nostr_relay.rs
@@ -82,7 +82,7 @@ impl Grasp01NostrRelayTests {
             
             // Get npub for clone URL
             let npub = client.public_key().to_bech32()
-                .map_err(|e| format!("Failed to convert pubkey to npub: {}", e))?;
+                .map_err(|e| format!("Failed to convert public key to bech32 npub format: {}", e))?;
             
             // Build kind 30617 repository announcement
             let event = client.event_builder(Kind::GitRepoAnnouncement, "")
@@ -92,11 +92,11 @@ impl Grasp01NostrRelayTests {
                 .tag(Tag::custom(TagKind::Custom("clone".into()), vec![format!("{}/{}/{}.git", http_url, npub, repo_id)]))
                 .tag(Tag::custom(TagKind::Custom("relays".into()), vec![relay_url.clone()]))
                 .build(client.keys())
-                .map_err(|e| format!("Failed to build event: {}", e))?;
+                .map_err(|e| format!("Failed to build repository announcement event (kind 30617): {}", e))?;
             
             // Send the event
             let event_id = client.send_event(event.clone()).await
-                .map_err(|e| format!("Failed to send event: {}", e))?;
+                .map_err(|e| format!("Failed to send repository announcement to relay: {}", e))?;
             
             // Query back to verify it was accepted and stored
             let filter = Filter::new()
@@ -105,17 +105,23 @@ impl Grasp01NostrRelayTests {
                 .identifier(&repo_id);
             
             let events = client.query(filter).await
-                .map_err(|e| format!("Failed to query events: {}", e))?;
+                .map_err(|e| format!("Failed to query events from relay: {}", e))?;
             
             // Verify we got the event back
             if events.is_empty() {
-                return Err("Event was not stored in relay (possibly rejected)".to_string());
+                return Err(format!(
+                    "Event was not stored in relay (possibly rejected). Event ID: {}, Repo ID: {}",
+                    event_id, repo_id
+                ));
             }
             
             // Verify it's the same event
             let stored_event = events.iter()
                 .find(|e| e.id == event_id)
-                .ok_or("Stored event ID doesn't match sent event")?;
+                .ok_or(format!(
+                    "Stored event ID doesn't match sent event. Expected: {}, Got {} events",
+                    event_id, events.len()
+                ))?;
             
             // Verify key tags are present
             let has_clone_tag = stored_event.tags.iter()
@@ -158,7 +164,7 @@ impl Grasp01NostrRelayTests {
             let relay_url = client.client().relays().await
                 .keys()
                 .next()
-                .ok_or("No relay connected")?
+                .ok_or("No relay connected - client has no active relay connections")?
                 .to_string();
             
             // Create unique repository identifier
@@ -186,11 +192,15 @@ impl Grasp01NostrRelayTests {
                 .identifier(&repo_id);
             
             let events = client.query(filter).await
-                .map_err(|e| format!("Failed to query events: {}", e))?;
+                .map_err(|e| format!("Failed to query events from relay: {}", e))?;
             
             // Verify event was rejected (not stored)
             if events.iter().any(|e| e.id == event_id) {
-                return Err("Relay accepted announcement without service in clone tag - should reject".to_string());
+                return Err(format!(
+                    "Relay incorrectly accepted announcement without service in clone tag. \
+                    Event ID: {}, Clone URL: https://github.com/user/repo.git (should require {})",
+                    event_id, relay_url
+                ));
             }
             
             Ok(())
@@ -650,16 +660,21 @@ mod tests {
     use super::*;
     use crate::AuditConfig;
     
-    #[tokio::test]
-    #[ignore] // Requires running relay
-    async fn test_grasp01_nostr_relay_against_relay() {
-        // Read relay URL from environment variable - must be supplied
-        let relay_url = std::env::var("RELAY_URL")?;
-        
-        let config = AuditConfig::ci();
-        let client = AuditClient::new(&relay_url, config)
-            .await
-            .expect("Failed to connect to relay");
+#[tokio::test]
+#[ignore] // Requires running relay
+async fn test_grasp01_nostr_relay_against_relay() {
+    // Read relay URL from environment variable - must be supplied
+    let relay_url = std::env::var("RELAY_URL")
+        .expect("RELAY_URL environment variable must be set. Example: RELAY_URL=ws://localhost:18081");
+    
+    let config = AuditConfig::ci();
+    let client = AuditClient::new(&relay_url, config)
+        .await
+        .expect(&format!(
+            "Failed to connect to relay at {}. Ensure relay is running and accessible. \
+            Try: docker run --rm -p 18081:8081 ghcr.io/danconwaydev/ngit-relay:latest",
+            relay_url
+        ));
         
         let results = Grasp01NostrRelayTests::run_all(&client).await;
         results.print_report();