# AI Agent Maintenance Instructions

When maintaining this repository, you MUST adhere to the following rules based on the `REQUIREMENTS.md`.

## Guidelines for Adding/Modifying Services

1. **Volume Mapping**:
   - ALWAYS map system data to `/volume1/docker/<service>`.
   - ALWAYS map large user data to `/volume1/media/<type>`.
   - Use environment variables (e.g., `${DOCKER_BASE:-/volume1/docker}`) if possible for flexibility.

2. **Setup Scripts**:
   - If a setup script does not exist, CREATE one named `create_<service>_folders.sh` in the service directory.
   - Use the following template for scripts:
     ```bash
     #!/bin/bash
     BASE="/volume1/docker/service_name"
     MEDIA="/volume1/media/service_data"
     mkdir -p "$BASE/config" "$BASE/data" "$MEDIA"
     chown -R PUID:PGID "$BASE" "$MEDIA"
     chmod -R 750 "$BASE" "$MEDIA"
     ```
   - Ensure the script is idempotent (safe to run multiple times).

4. **Setup Documentation (SETUP.md)**:
   - Create a `SETUP.md` file in the service directory based on `SERVICE_SETUP_TEMPLATE.md`.
   - Explicitly highlight **MANUAL** steps like Synology user creation and PUID/PGID lookup.
   - Describe what the setup script does and what environment variables are needed.

5. **Docker Compose (Portainer Stacks)**:
   - Name the file `docker-compose.portainer.yml`.
   - Group dependent containers (DB, Cache) in the same file.
   - Use `user: "${PUID}:${PGID}"` unless root is required.
   - Prefer `env_file: stack.env` for environment variable management.

4. **Code Quality**:
   - Check for typos in filenames and configurations.
   - Ensure consistent naming conventions across all service directories.