# AGENTS.md

This file provides guidance to agents when working with code in this repository.

## Critical Documentation Context (Non-Obvious Only)

- **"FastCGI App"**: This is NOT a web server - it's a FastCGI application that nginx calls for dynamic operations
- **Two Config Systems**: File-based config (XDG) is priority 1, database config is fallback - don't assume standard config locations
- **Blob Storage Strategy**: Files stored WITH extensions but URLs accept any extension - counterintuitive to typical web serving
- **Admin API Auth**: Uses Nostr cryptographic events (kind 24242) not standard bearer tokens or sessions
- **Database Schema**: `blobs` table stores metadata, physical files in `blobs/` directory - database is authoritative
- **Build Requirements**: Requires local SQLite build, nostr_core_lib submodule, and specific FastCGI libraries
- **Testing Setup**: Tests require `nak` tool for Nostr event generation - not standard HTTP testing
- **Development Ports**: Local development uses port 9001, production typically uses nginx proxy on standard ports
- **Setup Wizard**: Interactive setup creates cryptographically signed config files - not typical config generation
- **Extension Handling**: nginx config uses wildcards to serve files regardless of URL extension - Blossom protocol compliance
- **Configuration Events**: Uses Nostr kind 33333 events with 1-year default expiration - XDG paths take priority over database