AI Agent Guidelines for /dev/push

# AI Agent Guidelines for /dev/push

This document provides comprehensive guidelines for AI agents working on the /dev/push codebase. It covers scripts, FastAPI application code, Docker/Compose, and project-wide conventions.

## Table of Contents

- [Scripts (`scripts/`)](#scripts-scripts)
- [FastAPI Application (`app/`)](#fastapi-application-app)
- [Docker & Compose](#docker--compose)
- [Project Structure](#project-structure)
- [General Conventions](#general-conventions)
- [Testing & Deployment](#testing--deployment)

---

## Scripts (`scripts/`)

These guidelines apply to every script under `scripts/` (install/start/stop/restart/helpers/etc.).

### Environment Detection & Paths

1. **Always source `scripts/lib.sh`** (use the `SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"` pattern, then `source "$SCRIPT_DIR/lib.sh"`). The lib sets `APP_DIR`, `DATA_DIR`, `ENV_FILE`, etc., and auto-detects dev vs prod via systemd or `DEVPUSH_ENV`.
2. **Do not hardcode relative paths.** Derive everything from `APP_DIR`, `DATA_DIR`, or `SCRIPT_DIR`.
3. **Expose overrides via `DEVPUSH_*` env vars** (already handled by the lib).