3 files changed, 232 insertions, 30 deletions

diff --git a/AGENTS.md b/AGENTS.md
index ec1ec60..d00d7fb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,6 +44,39 @@ 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.
 
+### Standard Testing Process (Recommended)
+
+**Use test-ngit-relay.sh for automated relay management:**
+
+This script handles all relay lifecycle management automatically:
+- Starts ngit-relay in isolated Docker container
+- Uses random port to avoid conflicts
+- Creates isolated temporary directories
+- Ensures cleanup on exit (success or failure)
+- Supports both audit and test modes
+
+**Basic Usage:**
+
+```bash
+# Run cargo test suite (recommended for GRASP-01 development)
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh --mode test
+
+# Run audit CLI tool (for quick validation)
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh
+
+# Get help
+cd grasp-audit && ./test-ngit-relay.sh --help
+```
+
+**Benefits:**
+- No manual relay startup required
+- Automatic cleanup prevents leftover containers
+- Random port selection avoids conflicts
+- Consistent environment across all runs
+- Proper test isolation
+
+**Note:** Manual relay setup is still available but test-ngit-relay.sh is recommended for development workflows.
+
 ### Running Single Test
 
 ```bash
@@ -140,6 +173,7 @@ See `docs/archive/2025-11-04-nostr-sdk-upgrade.md` for full migration.
 4. **Test isolation:** Integration tests need relay, marked with `#[ignore]`
 5. **Work directory:** All session docs go in `work/`, NOT root
 6. **Archive naming:** Use `YYYY-MM-DD-description.md` format
+7. **Use test-ngit-relay.sh**: Always use the test script for GRASP-01 tests - it handles cleanup and port management automatically
 
 ## File Restrictions by Mode
 
@@ -152,18 +186,19 @@ Code mode can only edit files matching specific patterns (enforced by system):
 ## Quick Reference
 
 ```bash
+# Recommended: Use test-ngit-relay.sh for all testing
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh --mode test
+
 # Build grasp-audit
 cd grasp-audit && nix develop -c cargo build
 
-# Run all tests (requires relay running, set RELAY_URL to match your port)
-cd grasp-audit && RELAY_URL="ws://localhost:18081" nix develop -c cargo test --ignored
+# Manual relay testing (if needed)
+# 1. Start relay: docker run --rm -p 18081:8081 ghcr.io/danconwaydev/ngit-relay:latest
+# 2. Run tests: RELAY_URL="ws://localhost:18081" nix develop -c cargo test --ignored
 
 # 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/README.md b/grasp-audit/README.md
index 3787fee..97a6429 100644
--- a/grasp-audit/README.md
+++ b/grasp-audit/README.md
@@ -12,6 +12,28 @@ A reusable audit and compliance testing tool for GRASP protocol implementations.
 
 ## Quick Start
 
+The fastest way to run GRASP-01 compliance tests:
+
+```bash
+# Run the test suite against ngit-relay
+cd grasp-audit
+nix develop -c bash test-ngit-relay.sh --mode test
+```
+
+This automatically:
+- ✅ Starts ngit-relay in an isolated Docker container
+- ✅ Runs all GRASP-01 compliance tests
+- ✅ Cleans up resources when finished
+
+**Currently Passing:** 4/18 tests (14 tests stubbed with "Not implemented yet")
+
+For more options:
+```bash
+./test-ngit-relay.sh --help
+```
+
+## Usage Examples
+
 ### As a Library
 
 ```rust
@@ -124,6 +146,8 @@ cargo run --example simple_audit
 
 ## Testing
 
+> **TL;DR:** See the [Quick Start](#quick-start) section for the fastest way to run tests.
+
 ### Unit Tests
 
 ```bash
@@ -134,20 +158,18 @@ nix develop
 cargo test
 ```
 
-### Integration Tests Against ngit-relay docker image
+### Integration Tests
 
-Test against the reference GRASP implementation to ensure compatibility.
+The recommended approach is [`test-ngit-relay.sh`](test-ngit-relay.sh), which handles all relay lifecycle management automatically.
 
-**Automated Script (Recommended):**
+See the [Quick Start](#quick-start) section for common usage patterns.
 
-```bash
-# Handles setup, testing, and cleanup automatically
-./test-ngit-relay.sh
-```
+**Advanced: Manual Relay Setup**
 
-See `test-ngit-relay.sh` for full setup/cleanup details.
+<details>
+<summary>Click to expand manual testing instructions</summary>
 
-**Manual Testing:**
+For advanced use cases where you need direct control over the relay:
 
 ```bash
 # Start relay on a specific port (example uses 18081)
@@ -160,6 +182,8 @@ grasp-audit audit --relay ws://localhost:18081 --mode ci
 RELAY_URL="ws://localhost:18081" cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture
 ```
 
+</details>
+
 ## Architecture
 
 ```
diff --git a/grasp-audit/test-ngit-relay.sh b/grasp-audit/test-ngit-relay.sh
index 356eed1..bd4b155 100755
--- a/grasp-audit/test-ngit-relay.sh
+++ b/grasp-audit/test-ngit-relay.sh
@@ -1,36 +1,144 @@
 #!/bin/bash
 set -e
 
+# =============================================================================
+# Script: test-ngit-relay.sh
+# Purpose: Test ngit-relay against GRASP specifications
+#
+# This script automates the process of:
+# 1. Starting a fresh ngit-relay instance in Docker
+# 2. Running either grasp-audit CLI or cargo test suite
+# 3. Cleaning up all resources on exit (via EXIT trap)
+#
+# Features:
+# - Automatic cleanup via EXIT trap (runs even on failure)
+# - Random port selection (20000-30000) to avoid conflicts
+# - Unique temporary directories per run
+# - Support for both audit and test execution modes
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Help Function
+# -----------------------------------------------------------------------------
+show_help() {
+    cat << EOF
+Usage: $(basename "$0") [OPTIONS]
+
+Test ngit-relay against GRASP specifications
+
+OPTIONS:
+    --mode <audit|test>    Execution mode (default: audit)
+                           audit: Run grasp-audit CLI tool
+                           test: Run cargo test suite
+    --spec <spec>          Specification to test (default: nip01-smoke)
+                           Only used in audit mode
+    --help                 Show this help message
+
+EXAMPLES:
+    # Run audit with default settings (current behavior)
+    ./test-ngit-relay.sh
+
+    # Run cargo tests instead
+    ./test-ngit-relay.sh --mode test
+
+    # Run audit with specific spec
+    ./test-ngit-relay.sh --mode audit --spec grasp01
+
+EOF
+    exit 0
+}
+
+# -----------------------------------------------------------------------------
+# Argument Parsing
+# -----------------------------------------------------------------------------
+# Default values maintain backward compatibility
+MODE="audit"
+SPEC="nip01-smoke"
+
+# Parse command-line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --mode)
+            MODE="$2"
+            shift 2
+            ;;
+        --spec)
+            SPEC="$2"
+            shift 2
+            ;;
+        --help)
+            show_help
+            ;;
+        *)
+            echo "❌ Unknown option: $1"
+            echo "Run with --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
+# Validate mode parameter
+if [ "$MODE" != "audit" ] && [ "$MODE" != "test" ]; then
+    echo "❌ Invalid mode: $MODE"
+    echo "Mode must be 'audit' or 'test'"
+    exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# Environment Setup
+# -----------------------------------------------------------------------------
 # Create temporary directory with random name
+# This ensures each test run is isolated and doesn't interfere with others
 TEST_DIR=$(mktemp -d -t grasp-audit-run-XXXXXXXXXX)
-# Pick a random port in the range 20000-30000
+
+# Pick a random port in the range 20000-30000 to avoid conflicts
 PORT=$((20000 + RANDOM % 10000))
-# Generate a unique container name suffix
+
+# Generate a unique container name suffix for parallel runs
 CONTAINER_SUFFIX=$RANDOM
 
 echo "🧹 Using temporary directory: $TEST_DIR"
 echo "🔌 Using port: $PORT"
+echo "🎯 Mode: $MODE $([ "$MODE" = "audit" ] && echo "(spec: $SPEC)" || echo "")"
 
-# Cleanup function
+# -----------------------------------------------------------------------------
+# Cleanup Function
+# -----------------------------------------------------------------------------
+# This function is called automatically on script exit via trap
+# The '|| true' pattern ensures cleanup continues even if individual steps fail
 cleanup() {
+    echo ""
     echo "🛑 Stopping relay..."
+    # Stop container gracefully, ignore errors if already stopped
     docker stop "grasp-audit-run-$CONTAINER_SUFFIX" 2>/dev/null || true
     
     echo "🧹 Cleaning up temporary directory..."
+    # Use alpine container to clean Docker-created files (may have different ownership)
     docker run --rm -v "$TEST_DIR:/data" alpine sh -c "rm -rf /data/*" 2>/dev/null || true
+    # Remove the temporary directory itself
     rm -rf "$TEST_DIR"
 }
 
-# Set trap to cleanup on exit
+# Set trap to run cleanup on ANY exit (success, failure, or interrupt)
+# This ensures resources are always cleaned up
 trap cleanup EXIT
 
+# -----------------------------------------------------------------------------
+# Docker Setup
+# -----------------------------------------------------------------------------
 echo "📁 Creating data directories..."
+# Create all required directories for ngit-relay in one command
 mkdir -p "$TEST_DIR"/{repos,blossom,relay-db,logs}
 
 echo "🚀 Starting ngit-relay..."
-# Remove any existing container with this name
+# Remove any existing container with this name (defensive cleanup)
 CONTAINER_NAME="grasp-audit-run-$CONTAINER_SUFFIX"
 docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
+
+# Start ngit-relay in detached mode with all required configuration
+# - Port mapping: expose internal 8081 on our random port
+# - Volume mounts: persist data in temp directory
+# - Proactive sync disabled: we control event submission via tests
 docker run --rm -d \
   --name "$CONTAINER_NAME" \
   -p "$PORT:8081" \
@@ -49,19 +157,54 @@ docker run --rm -d \
   ghcr.io/danconwaydev/ngit-relay:latest
 
 echo "⏳ Waiting for relay to start..."
+# Give the relay time to initialize before running tests
 sleep 3
 
-echo "🧪 Running tests..."
-echo ""
-echo "Note: ngit-relay only accepts Git-related events (NIP-34)."
-echo "Some NIP-01 smoke tests will fail (expected behavior)."
-echo "Validation tests should pass."
-echo ""
+# -----------------------------------------------------------------------------
+# Test Execution
+# -----------------------------------------------------------------------------
+# Execute tests based on selected mode
+# The EXIT trap ensures cleanup happens regardless of test outcome
 
-# Run the CLI tool (cleanup happens via trap even on failure)
-RELAY_URL="ws://localhost:$PORT" cargo run -- audit --relay "ws://localhost:$PORT" --mode ci --spec nip01-smoke || {
-    echo "⚠️  Some tests failed (expected for ngit-relay)"
-    echo "    Validation tests should have passed"
-}
+if [ "$MODE" = "audit" ]; then
+    echo "🧪 Running audit mode (spec: $SPEC)..."
+    echo ""
+    echo "Note: ngit-relay only accepts Git-related events (NIP-34)."
+    echo "Some NIP-01 smoke tests will fail (expected behavior)."
+    echo "Validation tests should pass."
+    echo ""
+    
+    # Run grasp-audit CLI tool
+    # - RELAY_URL: Environment variable used by audit tool
+    # - --relay: Command-line parameter for relay address
+    # - --mode ci: Continuous integration mode (structured output)
+    # - --spec: Which specification to test
+    # The '|| { }' block provides user-friendly messaging on failure
+    RELAY_URL="ws://localhost:$PORT" cargo run -- audit \
+        --relay "ws://localhost:$PORT" \
+        --mode ci \
+        --spec "$SPEC" || {
+        echo "⚠️  Some tests failed (expected for ngit-relay)"
+        echo "    Validation tests should have passed"
+    }
+    
+elif [ "$MODE" = "test" ]; then
+    echo "🧪 Running cargo test mode..."
+    echo ""
+    
+    # Run cargo test suite
+    # - RELAY_URL: Environment variable tests use to connect
+    # - --lib: Only library tests (not integration tests in tests/)
+    # - test_grasp01_nostr_relay_against_relay: Specific test module
+    # - --ignored: Run tests marked with #[ignore] (these need relay)
+    # - --nocapture: Show println! output from tests
+    RELAY_URL="ws://localhost:$PORT" cargo test \
+        --lib test_grasp01_nostr_relay_against_relay \
+        -- --ignored --nocapture || {
+        echo "⚠️  Some tests failed"
+        echo "    Review output above for details"
+    }
+fi
 
+echo ""
 echo "✅ Done!"