# 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
- **Admin Key File**: `.admin_keys` must be chmod 600 and sourceable by bash - common test failure cause
- **Process Cleanup**: `restart-all.sh` performs force kill if graceful shutdown fails - check logs for hung processes