docs: use Diátaxis structure

1 files changed, 209 insertions, 0 deletions

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)*