From 22557f15d6a7b77f72d4597fc05aa06346495a33 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Tue, 4 Nov 2025 09:31:57 +0000
Subject: docs: major cleanup and reorganization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Archive 30 completed session documents to docs/archive/
- Extract learnings to docs/learnings/ (nix-flakes, nostr-sdk, grasp-audit)
- Create CURRENT_STATUS.md as single source of truth
- Create AGENTS.md with documentation guidelines
- Create docs/archive/README.md for archive organization
- Clean root directory: 32 files → 4 files

Root directory now contains only:
- README.md (project overview)
- AGENTS.md (documentation guidelines)
- CURRENT_STATUS.md (current state)
- CLEANUP_SUMMARY.md (cleanup report)

All historical documents preserved in docs/archive/ with proper dating.
All reusable knowledge extracted to docs/learnings/.

Benefits:
- Easy to find current information
- Clear document lifecycle
- No more documentation sprawl
- Learnings are accessible and reusable
- Better onboarding for new developers/agents

File counts:
- Root: 4 (was 32)
- Permanent docs: 7
- Learnings: 3 (new)
- Archive: 32 (new)
- Total: 49 well-organized docs
---
 docs/archive/2025-11-03-quick-reference.md | 449 +++++++++++++++++++++++++++++
 1 file changed, 449 insertions(+)
 create mode 100644 docs/archive/2025-11-03-quick-reference.md

(limited to 'docs/archive/2025-11-03-quick-reference.md')

diff --git a/docs/archive/2025-11-03-quick-reference.md b/docs/archive/2025-11-03-quick-reference.md
new file mode 100644
index 0000000..b9b9943
--- /dev/null
+++ b/docs/archive/2025-11-03-quick-reference.md
@@ -0,0 +1,449 @@
+# ⚡ Quick Reference - grasp-audit
+
+**Last Updated:** November 4, 2025  
+**Status:** ✅ Ready for use
+
+---
+
+## 🚀 One-Minute Quick Start
+
+```bash
+# Build and test
+cd grasp-audit
+nix develop --command cargo build
+nix develop --command cargo test --lib
+
+# Run integration test (needs relay)
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay  # Terminal 1
+cd grasp-audit && nix develop --command cargo test --ignored  # Terminal 2
+```
+
+---
+
+## 📋 Common Commands
+
+### Build
+```bash
+cargo build                    # Debug build
+cargo build --release          # Release build
+cargo build --bin grasp-audit  # CLI only
+cargo build --example simple_audit  # Example
+```
+
+### Test
+```bash
+cargo test --lib               # Unit tests (no relay needed)
+cargo test --ignored           # Integration tests (relay required)
+cargo test --all               # All tests
+cargo test test_name           # Specific test
+RUST_LOG=debug cargo test     # With logging
+```
+
+### Run
+```bash
+# CLI
+cargo run -- audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke
+
+# Example
+cargo run --example simple_audit
+
+# Help
+cargo run -- --help
+cargo run -- audit --help
+```
+
+### Development
+```bash
+cargo clippy                   # Linting
+cargo fmt                      # Format code
+cargo fmt --check             # Check formatting
+cargo doc --open              # Generate docs
+cargo clean                   # Clean build
+```
+
+---
+
+## 🧪 Testing
+
+### Start Test Relay
+```bash
+# Option 1: Docker (easiest)
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
+
+# Option 2: Build from source
+git clone https://github.com/rust-nostr/nostr
+cd nostr/crates/nostr-relay-builder
+cargo run --example basic
+```
+
+### Run Tests
+```bash
+# Unit tests (fast, no relay)
+cargo test --lib
+
+# Integration tests (needs relay)
+cargo test --ignored
+
+# Specific test
+cargo test test_websocket_connection -- --nocapture
+
+# All tests
+cargo test --all
+```
+
+### Expected Results
+```
+Unit Tests:     12 passed, 0 failed
+Integration:    6 passed (with relay)
+Build Time:     ~0.1s (incremental)
+Test Time:      ~0.5s
+```
+
+---
+
+## 📁 File Locations
+
+### Source Code
+```
+grasp-audit/src/
+├── lib.rs                     # Library root
+├── audit.rs                   # Audit framework
+├── client.rs                  # Nostr client
+├── isolation.rs               # Test isolation
+├── result.rs                  # Result types
+├── bin/grasp-audit.rs        # CLI tool
+└── specs/
+    ├── mod.rs                # Spec registry
+    └── nip01_smoke.rs        # Smoke tests
+```
+
+### Examples
+```
+grasp-audit/examples/
+└── simple_audit.rs           # Basic usage
+```
+
+### Documentation
+```
+grasp-audit/
+├── README.md                 # Main documentation
+├── QUICK_START.md           # Detailed setup
+└── Cargo.toml               # Dependencies
+
+Project Root/
+├── VERIFICATION_COMPLETE.md  # Verification report
+├── READY_FOR_NEXT_PHASE.md  # Next steps
+├── SESSION_COMPLETE_2025_11_04.md  # Session summary
+└── QUICK_REFERENCE.md       # This file
+```
+
+---
+
+## 🎯 CLI Usage
+
+### Basic Usage
+```bash
+grasp-audit audit \
+  --relay ws://localhost:7000 \
+  --mode ci \
+  --spec nip01-smoke
+```
+
+### Options
+```
+--relay <URL>     Relay WebSocket URL (required)
+--mode <MODE>     Test mode: ci or production
+--spec <SPEC>     Test specification to run
+```
+
+### Modes
+- **ci**: Ephemeral test events (auto-cleanup)
+- **production**: Permanent audit trail
+
+### Specs
+- **nip01-smoke**: 6 basic NIP-01 tests
+
+---
+
+## 📊 Test Specifications
+
+### NIP-01 Smoke Tests
+1. `websocket_connection` - Basic connectivity
+2. `send_receive_event` - Event round-trip
+3. `create_subscription` - REQ message
+4. `close_subscription` - CLOSE message
+5. `reject_invalid_signature` - Validation
+6. `reject_invalid_event_id` - Validation
+
+### Future Specs (Planned)
+- `grasp-01-relay` - GRASP-01 compliance
+- `grasp-02-sync` - Proactive sync
+- `grasp-05-archive` - Archive mode
+
+---
+
+## 🔧 Troubleshooting
+
+### Build Fails: "linker 'cc' not found"
+```bash
+# Use nix develop
+cd grasp-audit
+nix develop
+cargo build
+```
+
+### Tests Fail: "Connection refused"
+```bash
+# Check relay is running
+docker ps | grep nostr
+
+# Start relay
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
+
+# Test connection
+curl -I http://localhost:7000
+```
+
+### Integration Tests Timeout
+```bash
+# Increase timeout in test code
+# Or use a faster relay
+# Or check network/firewall
+```
+
+### Nix Issues
+```bash
+# Update flake
+nix flake update
+
+# Rebuild environment
+nix develop --rebuild
+```
+
+---
+
+## 📚 Key Resources
+
+### Documentation
+- [README.md](grasp-audit/README.md) - Full documentation
+- [QUICK_START.md](grasp-audit/QUICK_START.md) - Setup guide
+- [VERIFICATION_COMPLETE.md](VERIFICATION_COMPLETE.md) - Current status
+- [READY_FOR_NEXT_PHASE.md](READY_FOR_NEXT_PHASE.md) - Next steps
+
+### Code Examples
+- [nip01_smoke.rs](grasp-audit/src/specs/nip01_smoke.rs) - Test examples
+- [simple_audit.rs](grasp-audit/examples/simple_audit.rs) - Usage example
+- [client.rs](grasp-audit/src/client.rs) - Client API
+
+### External Links
+- [GRASP Protocol](https://gitworkshop.dev/danconwaydev.com/grasp)
+- [nostr-sdk 0.43](https://docs.rs/nostr-sdk/0.43.0)
+- [rust-nostr](https://github.com/rust-nostr/nostr)
+- [NIP-01](https://nips.nostr.com/01)
+- [NIP-34](https://nips.nostr.com/34)
+
+---
+
+## 🎯 Common Tasks
+
+### Run Full Verification
+```bash
+# Build
+cargo build
+
+# Unit tests
+cargo test --lib
+
+# Start relay
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay &
+
+# Integration tests
+cargo test --ignored
+
+# CLI test
+cargo run -- audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke
+
+# Stop relay
+docker stop $(docker ps -q --filter ancestor=scsibug/nostr-rs-relay)
+```
+
+### Add New Test
+```bash
+# 1. Edit src/specs/nip01_smoke.rs
+# 2. Add test function
+# 3. Register in run_smoke_tests()
+# 4. Test it
+cargo test test_your_new_test -- --nocapture
+```
+
+### Create New Spec
+```bash
+# 1. Create src/specs/your_spec.rs
+# 2. Implement tests
+# 3. Add to src/specs/mod.rs
+# 4. Register in CLI
+# 5. Test
+cargo test --all
+```
+
+### Release Build
+```bash
+# Build release
+cargo build --release
+
+# Binary location
+./target/release/grasp-audit
+
+# Install globally
+cargo install --path grasp-audit
+grasp-audit --help
+```
+
+---
+
+## 📊 Project Stats
+
+### Code
+- **Total Lines:** 1,079 lines Rust
+- **Source Files:** 9 files
+- **Test Files:** 3 files
+- **Examples:** 1 file
+
+### Tests
+- **Unit Tests:** 12 tests
+- **Integration Tests:** 6 tests
+- **Pass Rate:** 100%
+
+### Performance
+- **Build Time:** ~0.1s (incremental)
+- **Test Time:** ~0.5s (unit)
+- **Total Verification:** <1 minute
+
+### Dependencies
+- **nostr-sdk:** 0.43.0 (latest)
+- **Rust:** 1.91.0
+- **Nix:** Latest stable
+
+---
+
+## ✅ Status Checklist
+
+### Working ✅
+- [x] Build system
+- [x] Unit tests
+- [x] CLI tool
+- [x] Examples
+- [x] Documentation
+
+### Ready ⏳
+- [ ] Integration tests (needs relay)
+- [ ] End-to-end testing (needs relay)
+- [ ] Performance testing
+
+### Planned 🔜
+- [ ] GRASP-01 tests
+- [ ] ngit-grasp relay
+- [ ] Full compliance
+
+---
+
+## 🚀 Next Steps
+
+### Today (30 min)
+```bash
+# 1. Start relay
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
+
+# 2. Run integration tests
+cd grasp-audit
+nix develop --command cargo test --ignored
+
+# 3. Test CLI
+nix develop --command cargo run -- audit \
+  --relay ws://localhost:7000 \
+  --mode ci \
+  --spec nip01-smoke
+```
+
+### This Week
+- Implement GRASP-01 tests OR
+- Start ngit-grasp relay OR
+- Both in parallel
+
+### Next 2-3 Weeks
+- Complete GRASP-01 compliance
+- Full integration testing
+- Production ready
+
+---
+
+## 💡 Tips
+
+### Fast Development
+```bash
+# Use nix develop for consistent environment
+nix develop
+
+# Use cargo watch for auto-rebuild
+cargo install cargo-watch
+cargo watch -x test
+
+# Use cargo-expand to see macros
+cargo install cargo-expand
+cargo expand
+```
+
+### Debugging
+```bash
+# Run with logging
+RUST_LOG=debug cargo test -- --nocapture
+
+# Run specific test
+cargo test test_name -- --nocapture
+
+# Use rust-lldb or rust-gdb
+rust-lldb ./target/debug/grasp-audit
+```
+
+### Performance
+```bash
+# Profile build
+cargo build --timings
+
+# Benchmark
+cargo bench
+
+# Check binary size
+ls -lh ./target/release/grasp-audit
+```
+
+---
+
+## 📞 Getting Help
+
+### Documentation
+1. Check README.md
+2. Read QUICK_START.md
+3. Review examples/
+4. See inline docs: `cargo doc --open`
+
+### Troubleshooting
+1. Check this file
+2. Review VERIFICATION_COMPLETE.md
+3. Read error messages carefully
+4. Check GitHub issues
+
+### Community
+- GRASP Protocol: https://gitworkshop.dev/danconwaydev.com/grasp
+- rust-nostr: https://github.com/rust-nostr/nostr
+- Nostr: https://nostr.com
+
+---
+
+**Quick Reference Version:** 1.0  
+**Last Updated:** November 4, 2025  
+**Status:** ✅ Current
+
+---
+
+*Keep this file handy for quick lookups! 📌*
-- 
cgit v1.2.3