portioner/.agent/instructions.md

# 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 (Intelligent Dry-run by default):
     ```bash
     #!/bin/bash
     DRY_RUN=true
     if [[ "$1" == "--run" || "$1" == "-r" ]]; then DRY_RUN=false; fi

     if [ "$DRY_RUN" = "true" ]; then
         echo "--- DRY RUN MODE ---"
         echo "To apply changes, run: sudo bash $0 --run"
         echo "--------------------"
     fi

     run_mkdir() {
         local path=$1
         if [ -d "$path" ]; then
             echo "[OK] Folder exists, no changes will be made: $path"
         else
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CREATE] Folder: $path"; else mkdir -p "$path"; fi
         fi
     }

     run_chown_recursive() {
         local owner=$1; local path=$2
         local uid=${owner%%:*}; local gid=${owner#*:}
         
         if [ ! -d "$path" ]; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL SET] Owner to $owner upon creation: $path"; else chown -R "$owner" "$path"; fi
             return
         fi

         if find "$path" \( ! -uid "$uid" -o ! -gid "$gid" \) | grep -q .; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CHANGE] Owner to $owner (recursive): $path"; else chown -R "$owner" "$path"; fi
         else
             echo "[OK] Owner is $owner, no changes will be made: $path"
         fi
     }
     
     run_chmod_recursive() {
         local mode=$1; local path=$2
         if [ ! -d "$path" ]; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL SET] Permissions to $mode upon creation: $path"; else chmod -R "$mode" "$path"; fi
             return
         fi
         if find "$path" ! -perm -"$mode" | grep -q .; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CHANGE] Permissions to $mode (recursive): $path"; else chmod -R "$mode" "$path"; fi
         else
             echo "[OK] Permissions are $mode, no changes will be made: $path"
         fi
     }
     ```
   - 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.