AGENTS.md - Non-obvious Information for stable-diffusion.cpp-rest

This document contains only non-obvious, project-specific information that agents need to know.

Critical Build Gotchas

NEVER delete build/_deps folder - Rebuilding dependencies takes hours
Use cd webui; npm run build-static for webui-only changes (no server restart needed)
Web UI is served from build/webui/ with base path /ui
Models directory is ALWAYS /data/SD_MODELS/ (not project root)

Architecture-Specific Patterns

Dual Model Loading Paths

The project uses intelligent model detection with two different loading paths:

Traditional models (SD 1.5/2.1/SDXL) → ctxParams.model_path
Modern architectures (Flux/SD3/Qwen2VL) → ctxParams.diffusion_model_path

String Lifetime Management

When passing strings to stable-diffusion.cpp:

Ensure string lifetime exceeds the entire generation process
Use std::string with proper scope management
Avoid temporary string objects in API calls

Server Lifecycle Constraints

NEVER kill running server processes - User manages server lifecycle
Agents should not start/stop servers unless explicitly requested
Start server in background during testing with full path to models directory
Server automatically serves updated webui files after npm run build-static

Authentication Patterns

Unix auth generates pseudo-tokens that must be validated properly
JWT tokens require proper expiration handling
API keys are static and stored in configuration

Progress Callback Cleanup

Progress callbacks must be cleaned up after generation completes
Use RAII patterns for callback management
Ensure callback deregistration to prevent memory leaks

Path Management Requirements

Always use absolute paths when printing to console (std::cout)
Model paths must be fully qualified paths
Web UI assets use /ui base path in all requests

Counterintuitive Practices

Keep project directory clean - no output/queue directories in root
Use ninja instead of make for faster builds
Web UI development can happen without server restart
Model architecture detection happens at runtime, not compile time

MCP Tools Integration

Always use available MCP tools for task efficiency
Gogs MCP tools for repository issue management
Create issues for all non-trivial tasks
Mark issues as done when tasks complete