# AGENTS.md

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

## Critical Project-Specific Rules

- **Database Path**: Always use `db/ginxsom.db` - this is hardcoded, not configurable
- **SQLite Build**: Uses local SQLite 3.37.2 in `sqlite3-build/` directory, NOT system SQLite
- **Local Development**: Everything runs locally on port 9001, never use system nginx on port 80
- **FastCGI Socket**: Uses `/tmp/ginxsom-fcgi.sock` for FastCGI communication
- **Config Priority**: File-based config (XDG locations) overrides database config
- **Admin Auth**: Uses Nostr events for admin API authentication (kind 24242 with "admin" tag)
- **Blob Storage**: Files stored as `blobs/<sha256>.<ext>` where extension comes from MIME type
- **Build Directory**: Must create `build/` directory before compilation
- **Test Files**: Tests are in the tests/ directory, and they should be run from the root, i.e. 'tests/mirror_test_bud04.sh'


## Non-Standard Commands

```bash
# make clean && make && Restart nginx
./restart-all.sh

# Start FastCGI daemon
./scripts/start-fcgi.sh

# Test admin API with authentication
source .admin_keys && ./scripts/test_admin.sh

# Setup wizard (creates signed config events)
./scripts/setup.sh

```

## Critical Architecture Notes

- FastCGI app handles HEAD/PUT/DELETE requests, nginx serves GET directly from disk
- Two-tier config: File config (signed Nostr events) + database config (key-value)
- Admin API requires Nostr event signatures with specific tag structure
- Database is single source of truth for blob existence (not filesystem)
- Extension handling: URLs work with any extension, files stored with correct extension