ngit-grasp/docs

ngit-grasp Documentation

Welcome to the ngit-grasp documentation! We use the Diátaxis framework to organize our documentation into four types, each serving a different purpose.

                    PRACTICAL          THEORETICAL
                    ─────────          ───────────
                    
LEARNING      │   Tutorials    │    Explanation   │
              │                │                  │
              │  Getting       │   Architecture   │
              │  Started       │   Decisions      │
              │                │                  │
              ├────────────────┼──────────────────┤
              │                │                  │
WORKING       │  How-To        │    Reference     │
              │  Guides        │                  │
              │                │   API Docs       │
              │  Deployment    │   Protocols      │
              │  Testing       │                  │
              │                │                  │

📚 Documentation Types

🎓 Tutorials - Learning by Doing

Purpose: Learn the basics through practical steps
For: Newcomers getting started
Style: Step-by-step lessons with guaranteed outcomes

• Getting Started - Your first ngit-grasp setup
• Running Your First Audit - Using grasp-audit tool

🔧 How-To Guides - Solving Problems

Purpose: Accomplish specific tasks
For: Users with basic knowledge solving real problems
Style: Practical recipes and solutions

• Deploy ngit-grasp - Choose Docker, NixOS, Linux, Proxmox, or managed hosting
• Deployment contract - Shared runtime and persistence requirements
• Configure Nix Flakes - Nix development environment
• Run Compliance Tests - GRASP compliance testing
• Upgrade nostr-sdk - Handling SDK upgrades

📖 Reference - Technical Information

Purpose: Look up technical details
For: Users who know what they're looking for
Style: Dry, factual, comprehensive

• Git Protocol - Git Smart HTTP protocol details
• GRASP Protocol - GRASP specification details
• Configuration - All config options
• API Reference - Internal API documentation

💡 Explanation - Understanding Concepts

Purpose: Understand the "why" and design decisions
For: Users wanting deeper understanding
Style: Discussion, context, alternatives

• Architecture Overview - System design and components
• Inline Authorization - Why we chose this approach
• Administration Vision - Nostr-authenticated management, embedded UI, and runtime configuration
• Comparison with ngit-relay - How we differ from reference
• Design Decisions - Key architectural choices

---

🚀 Quick Start Paths

I'm brand new to ngit-grasp

1. Read README.md for project overview
2. Follow Getting Started Tutorial
3. Understand Architecture Overview

I want to deploy ngit-grasp

1. Review Configuration Reference
2. Choose an environment in Deploy ngit-grasp
3. Verify the deployment and test its backup

I want to develop on ngit-grasp

1. Follow Getting Started Tutorial
2. Read Architecture Overview
3. Check Nix Flakes How-To
4. Review Test Strategy

I want to understand the design

1. Read Inline Authorization Explanation
2. Review Design Decisions
3. Compare with ngit-relay Comparison

I'm looking for specific information

• Protocol details? → Reference
• Configuration options? → Configuration Reference
• Git protocol? → Git Protocol Reference

---

📂 Additional Resources

Archive

Historical session notes and completed work. Useful for understanding project evolution but not required reading.

Learnings

DEPRECATED - Being migrated to Diátaxis structure:

• Gotchas → How-To Guides
• Patterns → Reference or Explanation
• Notes → Appropriate category

---

🤝 Contributing to Documentation

When adding documentation, ask yourself:

Is it a tutorial?

• Does it teach a beginner?
• Is it a complete lesson with guaranteed outcome?
• → Add to tutorials/

Is it a how-to guide?

• Does it solve a specific problem?
• Is it a recipe for accomplishing a task?
• → Add to how-to/

Is it reference material?

• Is it technical information?
• Will people look it up when needed?
• → Add to reference/

Is it explanation?

• Does it explain "why"?
• Does it discuss alternatives or design?
• → Add to explanation/

See Diátaxis documentation for more guidance.

---

📊 Project Status

ALPHA - Under active development. Core functionality working, API may change.

Completed

• ✅ grasp-audit compliance testing tool
• ✅ Nix flake development environment
• ✅ nostr-sdk 0.43 upgrade
• ✅ Documentation restructure (Diátaxis)

In Progress

• 🔄 Core ngit-grasp server implementation
• 🔄 GRASP-01 compliance

Planned

• 🔜 GRASP-02 (Proactive Sync)
• 🔜 GRASP-05 (Archive)

---

🔗 External Links

• GRASP Protocol Specification
• NIP-34 (Git Stuff)
• Diátaxis Framework
• rust-nostr Documentation

---

Documentation structure based on Diátaxis
Last updated: November 4, 2025