docs: use Diátaxis structure

3 files changed, 595 insertions, 0 deletions

diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
new file mode 100644
index 0000000..3eb0c5c
--- /dev/null
+++ b/docs/tutorials/README.md
@@ -0,0 +1,116 @@
+# Tutorials
+
+**Learning-oriented documentation** - Learn by doing with step-by-step guidance.
+
+---
+
+## What Are Tutorials?
+
+Tutorials are **lessons** that teach you how to use ngit-grasp through practical, hands-on steps.
+
+**Characteristics:**
+- ✅ Learning-oriented (teach beginners)
+- ✅ Practical (you follow along)
+- ✅ Step-by-step with guaranteed outcomes
+- ✅ Complete from start to finish
+- ✅ Safe to experiment with
+
+**Not tutorials:**
+- ❌ Problem-solving guides (those are How-To)
+- ❌ Technical references (those are Reference)
+- ❌ Conceptual explanations (those are Explanation)
+
+---
+
+## Available Tutorials
+
+### [Getting Started](getting-started.md)
+**Time:** 15-20 minutes  
+**Learn:** Set up ngit-grasp development environment, build and test the code
+
+**You'll accomplish:**
+- Clone and build the project
+- Set up Nix development environment
+- Run tests successfully
+- Understand project structure
+
+**Start here if:** You're brand new to ngit-grasp
+
+---
+
+### [Running Your First Audit](first-audit.md)
+**Time:** 10-15 minutes  
+**Prerequisites:** [Getting Started](getting-started.md) completed  
+**Learn:** Use grasp-audit to check GRASP compliance
+
+**You'll accomplish:**
+- Run compliance tests against a relay
+- Interpret audit results
+- Use the audit tool library
+- Understand GRASP requirements
+
+**Start here if:** You want to test GRASP compliance
+
+---
+
+## Planned Tutorials
+
+### Deploying Your First GRASP Relay
+**Status:** 🔜 Planned (waiting for main server implementation)
+
+**You'll learn:**
+- Deploy ngit-grasp to production
+- Configure for your domain
+- Set up HTTPS with reverse proxy
+- Create your first repository
+
+---
+
+### Contributing Your First PR
+**Status:** 🔜 Planned
+
+**You'll learn:**
+- Find an issue to work on
+- Set up development environment
+- Make changes and test
+- Submit a pull request
+
+---
+
+## How to Use Tutorials
+
+1. **Follow in order** - Each step builds on previous ones
+2. **Actually do the steps** - Don't just read, type the commands
+3. **Expect success** - If something fails, check troubleshooting
+4. **Learn by doing** - Understanding comes from practice
+
+**Not sure if this is what you need?**
+- Want to solve a specific problem? → [How-To Guides](../how-to/)
+- Looking for technical details? → [Reference](../reference/)
+- Want to understand the design? → [Explanation](../explanation/)
+
+---
+
+## Contributing Tutorials
+
+When writing a tutorial:
+
+**DO:**
+- ✅ Start with a clear learning goal
+- ✅ Provide complete, tested steps
+- ✅ Include expected output
+- ✅ Add troubleshooting section
+- ✅ Keep it focused (one topic)
+- ✅ Test with a beginner
+
+**DON'T:**
+- ❌ Assume prior knowledge (or state prerequisites clearly)
+- ❌ Skip steps ("obviously you would...")
+- ❌ Explain every detail (link to Explanation docs)
+- ❌ Try to cover everything (keep scope small)
+
+See [Diátaxis: Tutorials](https://diataxis.fr/tutorials/) for detailed guidance.
+
+---
+
+*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*
diff --git a/docs/tutorials/first-audit.md b/docs/tutorials/first-audit.md
new file mode 100644
index 0000000..194a976
--- /dev/null
+++ b/docs/tutorials/first-audit.md
@@ -0,0 +1,270 @@
+# Tutorial: Running Your First GRASP Audit
+
+**Purpose:** Learn how to use grasp-audit to check GRASP compliance  
+**Time:** 10-15 minutes  
+**Prerequisites:** [Getting Started Tutorial](getting-started.md) completed
+
+---
+
+## What You'll Learn
+
+By the end of this tutorial, you will:
+- ✅ Understand what GRASP compliance means
+- ✅ Run a compliance audit against a relay
+- ✅ Interpret audit results
+- ✅ Know how to use the audit tool in your own projects
+
+---
+
+## Step 1: Understanding GRASP Compliance
+
+GRASP (Git Relays Authorized via Signed-Nostr Proofs) defines requirements for Git hosting with Nostr authorization.
+
+**Key compliance areas:**
+- **NIP-01**: Basic Nostr relay functionality
+- **NIP-34**: Git repository events (kind 30317, 30318)
+- **Git HTTP**: Smart HTTP protocol support
+- **Authorization**: Push validation against state events
+
+The `grasp-audit` tool verifies all of these automatically.
+
+---
+
+## Step 2: Start a Test Relay
+
+For this tutorial, we'll use a standard Nostr relay:
+
+```bash
+# In a separate terminal window:
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
+
+# Keep this running throughout the tutorial
+```
+
+**What this does:** Starts a NIP-01 compliant Nostr relay on port 7000.
+
+**Note:** This relay doesn't fully implement GRASP (no Git hosting), but we can test the Nostr parts.
+
+---
+
+## Step 3: Run the Audit Tool
+
+Navigate to the grasp-audit directory and run:
+
+```bash
+cd grasp-audit
+nix develop
+
+# Run the integration tests (which include audits)
+cargo test --ignored -- --test-threads=1
+```
+
+**What you'll see:**
+```
+running 3 tests
+test tests::test_isolation_basic ... ok
+test tests::test_isolation_cleanup ... ok  
+test tests::test_isolation_concurrent ... ok
+
+test result: ok. 3 passed; 0 failed; 0 ignored
+```
+
+**What just happened?** The audit tool:
+1. Connected to the relay on port 7000
+2. Checked NIP-01 compliance (event submission, retrieval)
+3. Tested isolation between test runs
+4. Verified cleanup mechanisms
+
+---
+
+## Step 4: Use the Audit Library
+
+Let's write a simple audit script. Create a new file:
+
+```bash
+# From grasp-audit directory
+cat > examples/my_audit.rs << 'EOF'
+use grasp_audit::prelude::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create an audit client
+    let client = AuditClient::new("ws://localhost:7000").await?;
+    
+    println!("✅ Connected to relay");
+    
+    // Test basic event submission
+    let test_event = client.create_test_event("Hello GRASP!").await?;
+    println!("✅ Created test event: {}", test_event.id);
+    
+    // Verify we can retrieve it
+    let retrieved = client.get_event(&test_event.id).await?;
+    println!("✅ Retrieved event successfully");
+    
+    println!("\n🎉 Basic audit passed!");
+    
+    Ok(())
+}
+EOF
+```
+
+**Note:** This is a simplified example. The actual audit tool has more sophisticated checks.
+
+---
+
+## Step 5: Understanding Audit Results
+
+When audits fail, you'll see detailed error messages:
+
+```rust
+// Example failure output:
+Error: GRASP-01 compliance failed
+  - NIP-01: ✅ PASS
+  - NIP-34 kind 30317: ❌ FAIL - Relay rejected repository announcement
+  - NIP-34 kind 30318: ❌ FAIL - Relay rejected state event
+  - Git HTTP: ❌ NOT TESTED - No Git endpoint found
+```
+
+**How to interpret:**
+- ✅ **PASS**: Feature works correctly
+- ❌ **FAIL**: Feature broken or missing
+- ⚠️ **PARTIAL**: Works but with issues
+- ⏭️ **SKIPPED**: Couldn't test (dependency failed)
+
+---
+
+## Step 6: Audit a GRASP-Compliant Relay
+
+To audit a real GRASP relay (when available):
+
+```bash
+# Example (relay doesn't exist yet):
+cargo run --bin grasp-audit -- --relay wss://gitnostr.com
+
+# Or use the library:
+let client = AuditClient::new("wss://gitnostr.com").await?;
+let results = client.run_full_audit().await?;
+println!("{}", results.summary());
+```
+
+**What this would check:**
+- Nostr relay functionality (NIP-01)
+- Git event acceptance (NIP-34)
+- Git HTTP endpoint availability
+- Push authorization logic
+- Multi-maintainer support
+
+---
+
+## Step 7: Automated Testing
+
+The audit tool is designed for CI/CD integration:
+
+```bash
+# Run all tests (unit + integration)
+cargo test --all
+
+# Run only integration tests
+cargo test --ignored
+
+# Generate coverage report
+cargo tarpaulin --ignored --out Html
+```
+
+**Use in CI:**
+```yaml
+# Example GitHub Actions
+- name: Run GRASP Compliance Tests
+  run: |
+    docker run -d -p 7000:7000 scsibug/nostr-rs-relay
+    cd grasp-audit
+    cargo test --ignored
+```
+
+---
+
+## What You've Accomplished
+
+Congratulations! You now:
+
+✅ Understand GRASP compliance requirements  
+✅ Can run the audit tool against a relay  
+✅ Know how to interpret audit results  
+✅ Can integrate audits into your workflow
+
+---
+
+## Next Steps
+
+### Learn more about testing:
+- Read [Compliance Testing How-To](../how-to/test-compliance.md)
+- Review [Test Strategy](../reference/test-strategy.md)
+
+### Understand the protocols:
+- Read [GRASP Protocol Reference](../reference/grasp-protocol.md)
+- Review [Git Protocol Reference](../reference/git-protocol.md)
+
+### Contribute to grasp-audit:
+- Check open issues
+- Add new compliance checks
+- Improve error messages
+
+---
+
+## Troubleshooting
+
+### "Connection refused" errors
+- Make sure the relay is running: `docker ps`
+- Check the port: `netstat -an | grep 7000`
+- Verify the URL: `ws://localhost:7000` (not `wss://`)
+
+### Tests timeout
+- Relay might be slow to start
+- Try running tests again after 5 seconds
+- Check Docker logs: `docker logs <container-id>`
+
+### "Event rejected" errors
+- Expected for non-GRASP relays
+- The relay might not support NIP-34
+- This is normal for the tutorial relay
+
+---
+
+## Deep Dive: How Audits Work
+
+The audit tool uses **isolated test environments**:
+
+```rust
+// Each test gets a unique identifier
+let isolation = IsolationContext::new("my-test");
+
+// Events are tagged with this identifier
+let event = isolation.create_event("test content").await?;
+
+// Cleanup removes only this test's events
+isolation.cleanup().await?;
+```
+
+**Why isolation matters:**
+- Tests don't interfere with each other
+- Can run tests in parallel
+- Easy cleanup (no leftover data)
+
+See [Test Strategy Reference](../reference/test-strategy.md) for details.
+
+---
+
+## Summary
+
+You've learned how to:
+- Run GRASP compliance audits
+- Interpret audit results
+- Use the audit library
+- Integrate audits into testing workflows
+
+**Next tutorial:** [Deploying ngit-grasp](../how-to/deploy.md) (when main server is ready)
+
+---
+
+*Part of the [ngit-grasp tutorials](./)*  
+*Previous: [Getting Started](getting-started.md)*
diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md
new file mode 100644
index 0000000..1a56985
--- /dev/null
+++ b/docs/tutorials/getting-started.md
@@ -0,0 +1,209 @@
+# Tutorial: Getting Started with ngit-grasp
+
+**Purpose:** Learn the basics of ngit-grasp through hands-on setup  
+**Time:** 15-20 minutes  
+**Prerequisites:** Basic Git and command-line knowledge
+
+---
+
+## What You'll Learn
+
+By the end of this tutorial, you will:
+- ✅ Have a working ngit-grasp development environment
+- ✅ Understand the basic project structure
+- ✅ Run the test suite successfully
+- ✅ Know where to go next
+
+---
+
+## Step 1: Clone the Repository
+
+First, get the source code:
+
+```bash
+git clone https://gitworkshop.dev/ngit-grasp
+cd ngit-grasp
+```
+
+**What just happened?** You cloned the ngit-grasp repository from the GRASP-enabled Git server.
+
+---
+
+## Step 2: Set Up Nix Development Environment
+
+ngit-grasp uses Nix flakes for reproducible development environments.
+
+```bash
+# Enter the development environment
+nix develop
+
+# You should see a new shell with all dependencies available
+```
+
+**What just happened?** Nix read `flake.nix` and created a shell with:
+- Rust toolchain (cargo, rustc)
+- Git
+- All required system libraries
+
+**Tip:** If `nix develop` doesn't work, you might be using an old Nix version. See the [Nix Flakes How-To](../how-to/nix-flakes.md) for help.
+
+---
+
+## Step 3: Explore the Project Structure
+
+Take a look around:
+
+```bash
+# View the project structure
+ls -la
+
+# Key directories:
+# - src/          - Main ngit-grasp source code (coming soon)
+# - grasp-audit/  - Compliance testing tool (working)
+# - docs/         - Documentation (you are here!)
+```
+
+**What you're seeing:**
+- `grasp-audit/` is a **subproject** with its own Cargo workspace
+- Main ngit-grasp server implementation is planned but not yet started
+- Documentation uses Diátaxis framework (tutorials, how-to, reference, explanation)
+
+---
+
+## Step 4: Work with grasp-audit
+
+The compliance testing tool is the first working component. Let's try it:
+
+```bash
+# Navigate to grasp-audit
+cd grasp-audit
+
+# Enter its development environment
+nix develop
+
+# Build the project
+cargo build
+
+# Run unit tests
+cargo test
+```
+
+**What just happened?** 
+- `grasp-audit` has its own `flake.nix` for isolated dependencies
+- Unit tests run without external dependencies
+- Integration tests (marked `#[ignore]`) require a Nostr relay
+
+---
+
+## Step 5: Run Your First Audit (Optional)
+
+If you want to try the audit tool against a real relay:
+
+```bash
+# In a separate terminal, start a test relay:
+docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
+
+# Back in grasp-audit directory:
+cargo test --ignored -- --test-threads=1
+```
+
+**What just happened?** Integration tests connected to the relay on port 7000 and verified GRASP compliance.
+
+**Note:** This step is optional. The relay must be running for these tests to pass.
+
+---
+
+## Step 6: Explore the Code
+
+Let's look at a simple example:
+
+```bash
+# From grasp-audit directory
+cat examples/simple_audit.rs
+```
+
+This shows how to use the `grasp-audit` library to check GRASP compliance.
+
+---
+
+## Step 7: Read the Documentation
+
+Now that you have a working setup, explore the documentation:
+
+```bash
+# From project root
+cd ..
+ls docs/
+```
+
+**Recommended reading order:**
+1. [Architecture Overview](../explanation/architecture.md) - Understand the design
+2. [Inline Authorization](../explanation/inline-authorization.md) - Key decision
+3. [Git Protocol Reference](../reference/git-protocol.md) - Technical details
+
+---
+
+## What You've Accomplished
+
+Congratulations! You now have:
+
+✅ A working Nix development environment  
+✅ Built and tested the grasp-audit tool  
+✅ Understanding of the project structure  
+✅ Knowledge of where to find more information
+
+---
+
+## Next Steps
+
+### If you want to contribute:
+1. Read [Architecture Overview](../explanation/architecture.md)
+2. Check open issues on the repository
+3. Review [Design Decisions](../explanation/decisions.md)
+
+### If you want to deploy:
+1. Follow [Deployment How-To](../how-to/deploy.md)
+2. Review [Configuration Reference](../reference/configuration.md)
+
+### If you want to understand GRASP:
+1. Read [GRASP Protocol Reference](../reference/grasp-protocol.md)
+2. Review [Comparison with ngit-relay](../explanation/comparison.md)
+
+### If you want to run compliance tests:
+1. Follow [Running Your First Audit Tutorial](first-audit.md)
+2. Review [Compliance Testing How-To](../how-to/test-compliance.md)
+
+---
+
+## Troubleshooting
+
+### "nix develop" doesn't work
+- You might need Nix with flakes enabled
+- See [Nix Flakes How-To](../how-to/nix-flakes.md)
+
+### Build errors in grasp-audit
+- Make sure you're in the `grasp-audit` directory
+- Run `nix develop` first
+- Check that you have network access (Cargo needs to download crates)
+
+### Tests fail
+- Unit tests should always pass
+- Integration tests (`--ignored`) require a relay on port 7000
+- Use `--test-threads=1` for integration tests
+
+---
+
+## Summary
+
+You've successfully set up ngit-grasp and learned:
+- How to use Nix flakes for development
+- The project structure (main server + grasp-audit tool)
+- How to build and test the code
+- Where to find documentation
+
+**Ready for more?** Try the [First Audit Tutorial](first-audit.md) next!
+
+---
+
+*Part of the [ngit-grasp tutorials](./)*  
+*Next: [Running Your First Audit](first-audit.md)*