# 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