# AGENTS.md

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

## Critical Coding Rules (Non-Obvious Only)

- **nostr_core_lib Integration**: Must use `nostr_sha256()` and `nostr_bytes_to_hex()` from nostr_core, NOT standard crypto libs
- **Database Connection Pattern**: Always use `sqlite3_open_v2()` with `SQLITE_OPEN_READONLY` or `SQLITE_OPEN_READWRITE` flags
- **Memory Management**: File data buffers must be freed after use - common pattern is `malloc()` for upload data, `free()` on all paths
- **Error Handling**: FastCGI responses must use `printf("Status: XXX\r\n")` format, NOT standard HTTP response format
- **String Safety**: Always null-terminate strings from SQLite results - use `strncpy()` with size-1 and explicit null termination
- **Hash Validation**: SHA-256 hashes must be exactly 64 hex chars - validate with custom `validate_sha256_format()` function
- **MIME Type Mapping**: Use centralized `mime_to_extension()` function - never hardcode file extensions
- **Authentication**: Nostr event parsing uses cJSON - always call `cJSON_Delete()` after use to prevent memory leaks
- **Configuration Loading**: File config takes priority over database - check XDG paths first, fallback to database
- **Blob Metadata**: Database is single source of truth - use `get_blob_metadata()`, not filesystem checks
- **nostr_core_lib Build**: Uses `build.sh` script, NOT `make` - run `./build.sh` to compile the library
- **Server Testing**: Use `./restart-all.sh` to properly restart and test ginxsom server, NOT direct binary execution
- **spawn-fcgi Parameters**: Must use `-M 666 -u "$USER" -g "$USER"` for socket permissions and ownership
- **Admin Event Structure**: Admin auth uses kind 24242 with "t" tag containing HTTP method, expiration typically 1 hour
- **Key File Permissions**: `.admin_keys` file must be chmod 600 or auth tests will fail
- **Development Environment**: Set `GINX_DEBUG=1` for pubkey extraction diagnostics during development