mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
DanConwayDev
7bca6e2482
Relay operators already have a stable Nostr identity for NIP-11 and NIP-42, but clients cannot resolve the domain itself to that key. Serve the NIP-05 root identifier so _@domain identifies a root-mounted relay without another key source. Add an exact root-level /.well-known/nostr.json route for GET and HEAD, serialize the relay-owner public key as lowercase hex under names._, retain permissive CORS, and give this route precedence over NIP-11 content negotiation. Derive NIP-11 support from the relay request path: only / advertises NIP-05, while nested relay paths omit it. Keep the changelog, architecture, README, and relay-owner configuration descriptions synchronized. The path check assumes the HTTP request path is the relay's public mount path; a future explicit base-path setting should remain the source for this decision if proxy routing hides that path. Named identities and recommended relay-hint mappings remain outside this change. Validated with 760 library tests, the root/non-root NIP-05 server integration test, strict all-target Clippy, cargo fmt, git diff checks, and Nix module parsing.
Reference
Information-oriented documentation - Technical details and specifications.
What Is Reference Documentation?
Reference documentation provides factual, technical information that you look up when needed.
Characteristics:
- ✅ Information-oriented (facts and data)
- ✅ Comprehensive and accurate
- ✅ Structured for lookup
- ✅ Dry and to-the-point
- ✅ Maintained as code changes
Not reference:
- ❌ Learning materials (those are Tutorials)
- ❌ Problem-solving guides (those are How-To)
- ❌ Conceptual explanations (those are Explanation)
Available Reference Documentation
Configuration
Complete reference for all configuration options
Contents:
- Environment variables
- Configuration file format
- Validation rules
- Examples for development/production/testing
Use when: You need to know what a config option does or what values are valid
Git Protocol
Git Smart HTTP protocol specification
Contents:
- Protocol overview
- Pkt-line format
- Request/response structure
- Reference updates format
- Parsing examples
Use when: You need to understand Git HTTP internals
Test Strategy
Testing approach and compliance framework
Contents:
- Test categories (unit, integration, compliance)
- GRASP compliance requirements
- Test isolation strategy
- Running tests
- Coverage requirements
Use when: You're writing tests or need to understand test structure
Planned Reference Documentation
GRASP Protocol
Status: 🔜 Planned
Contents:
- GRASP-01 requirements
- GRASP-02 (Proactive Sync)
- GRASP-05 (Archive)
- Event formats
- Validation rules
API Reference
Status: 🔜 Planned (waiting for main server)
Contents:
- HTTP endpoints
- Request/response formats
- Error codes
- Authentication
- Rate limiting
nostr-sdk Upgrade Guide
Status: 🔜 Planned
Contents:
- Version compatibility matrix
- Breaking changes by version
- Migration examples
- Common patterns
Event Formats
Status: 🔜 Planned
Contents:
- NIP-34 repository announcements (kind 30317)
- NIP-34 state events (kind 30318)
- Custom tags
- Validation rules
CLI Reference
Status: 🔜 Planned
Contents:
- Command-line arguments
- Subcommands
- Environment variables
- Exit codes
How to Use Reference Documentation
- Know what you're looking for - Reference is for lookup, not learning
- Use search or table of contents - Find the specific detail you need
- Check version - Ensure docs match your version
- Verify with code - Reference should match implementation
Not sure if this is what you need?
- New to the topic? → Tutorials
- Trying to solve a problem? → How-To Guides
- Want to understand concepts? → Explanation
Contributing Reference Documentation
When writing reference documentation:
DO:
- ✅ Be accurate and complete
- ✅ Use consistent structure
- ✅ Include all options/parameters
- ✅ Provide examples
- ✅ Update when code changes
- ✅ Use tables for structured data
DON'T:
- ❌ Explain concepts (link to Explanation)
- ❌ Provide tutorials (link to Tutorials)
- ❌ Solve problems (link to How-To)
- ❌ Include opinions or recommendations
Template:
# Reference: [Topic]
**Purpose:** [What this reference covers]
**Audience:** [Who needs this information]
---
## Overview
[Brief description of what's being documented]
---
## [Section 1]
### [Item]
**Description:** [What it is/does]
**Type:** [Data type]
**Default:** [Default value]
**Required:** [Yes/No]
**Examples:**
\`\`\`
[Example usage]
\`\`\`
**Notes:**
- [Important details]
---
## Related Documentation
- [Links to relevant docs]
See Diátaxis: Reference for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.