# Specification: Manual Slop Headless Backend

## Overview
Transform Manual Slop into a decoupled, container-friendly backend service. This track enables the core AI orchestration and tool execution logic to run without a GUI, exposing its capabilities via a secured REST API optimized for an Unraid Docker environment.

## Goals
- Decouple the GUI logic (`Dear PyGui`, `ImGui`) from the core AI and Tool logic.
- Implement a lightweight REST API server (FastAPI) to handle AI interactions.
- Ensure full compatibility with Unraid Docker networking and configuration patterns.
- Maintain the "Human-in-the-Loop" safety model through a remote confirmation mechanism.

## Functional Requirements

### 1. Headless Mode Lifecycle
- **Startup**: Provide a `--headless` flag or `[headless]` section in `manual_slop.toml` to skip GUI initialization.
- **Dependencies**: Ensure the app can start in environments without an X11/Wayland display or GPU.
- **Service Mode**: Support running as a persistent background daemon/service.

### 2. REST API (FastAPI)
- **Status/Health**: `/status` and `/health` endpoints for Docker/Unraid monitoring.
- **AI Interface**: `/generate` and `/stream` endpoints to interact with configured AI providers.
- **Tool Management**: Endpoints to list and execute tools (PowerShell/MCP).
- **Session Support**: Manage conversation history and project context via API.

### 3. Security & Authentication
- **API Key**: Require a `X-API-KEY` header for all sensitive endpoints.
- **Unraid Integration**: API keys should be configurable via Environment Variables (standard for Unraid templates).

### 4. Remote Confirmation Mechanism
- **Challenge/Response**: When a tool requires execution, the API should return a "Pending Confirmation" state.
- **Webhook/Poll**: Support a mechanism (e.g., a `/confirm/{id}` endpoint) for the future frontend to approve/deny actions.

## Non-Functional Requirements
- **Performance**: Headless mode should use significantly less memory/CPU than the GUI version.
- **Logging**: Use standard Python `logging` for Docker-compatible stdout/stderr output.
- **Portability**: Must run reliably inside a standard `python:3.11-slim` or similar Docker image.

## Acceptance Criteria
- [ ] Manual Slop starts successfully with `--headless` and no display environment.
- [ ] API is accessible via a configurable port (e.g., 8000).
- [ ] All API requests are rejected without a valid API Key.
- [ ] AI generation works via REST endpoints, returning structured JSON or a stream.
- [ ] Tool execution is successfully blocked until a separate "Confirm" API call is made.

## Out of Scope
- Building the actual Unraid GUI frontend (React/Vue/etc.).
- Multi-user authentication (OIDC/OAuth2).
- Native Unraid `.plg` plugin development (focusing on Docker).