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