AGENTS.md

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

Critical Debug Rules (Non-Obvious Only)

FastCGI Socket Issues: If socket /tmp/ginxsom-fcgi.sock exists but connection fails, remove it manually before restart
Local SQLite Binary: Debug with ./sqlite3-build/sqlite3 db/ginxsom.db, NOT system sqlite3
Authentication Debug: Failed auth shows error codes in nostr_core format - use nostr_strerror() for meanings
Memory Leaks: cJSON objects MUST be deleted after use - common leak source in auth parsing
File Permissions: Blob files need 644 permissions or nginx can't serve them - check with ls -la blobs/
Database Locks: SQLite connection must be closed on ALL code paths or database locks occur
Config Loading: File config errors are silent - check stderr for "CONFIG:" messages during startup
Admin Key Mismatch: Database admin_pubkey vs .admin_keys file often cause auth failures
Nginx Port Conflicts: Local nginx on 9001 conflicts with system nginx on 80 - check with netstat -tlnp
Hash Calculation: File data buffer must be complete before nostr_sha256() call or hash is wrong