docs: Formalize Synology NAS repo standards with REQUIREMENTS.md, maintenance instructions, and setup guides. Fix service typos and standardize filenames.

.agent/instructions.md

@@ -0,0 +1,38 @@
+# 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.

REQUIREMENTS.md

@@ -0,0 +1,29 @@
+# Synology NAS Docker Service Requirements
+
+This document outlines the mandatory standards for services managed in this repository via Portainer.
+
+## 1. User Management
+- **Dedicated User**: Every service must have a dedicated local user created on the Synology DSM.
+- **Non-Root Execution**: Containers must run under the service-specific PUID and PGID whenever possible.
+- **Root Exception**: Only services that strictly require root privileges (e.g., Traefik, Cloudflared in some network modes) are allowed to run as root.
+
+## 2. File and Folder Structure
+- **Base Path**: `/volume1/docker/`
+- **Service Data**: All configuration, database, and system-related files must reside in `/volume1/docker/<service_name>`.
+- **User Data (Large)**: Large user-managed files (e.g., ebooks, movies, paperless documents) must reside in `/volume1/media/<type>/`.
+- **Hierarchy Example**:
+  - `/volume1/docker/calibre/` (Config, DB)
+  - `/volume1/media/ebooks/` (EPUB/PDF files)
+
+## 3. Deployment and Setup
+- **Idempotent Scripts**: Every service must include a `create_<service>_folders.sh` script.
+- **Setup Documentation**: Every service folder must contain a `SETUP.md` file documenting the end-to-end flow, highlighting manual pre-setup steps (user creation, ID lookup).
+- **Script Requirements**:
+  - Must use `mkdir -p` to handle existing directories.
+  - Must set correct ownership (`chown`) and permissions (`chmod`) based on the service user.
+  - Must be safe to run multiple times without causing errors or data loss.
+- **Stack Grouping**: It is encouraged to group related containers (e.g., App, DB, Redis) into a single Portainer stack file.
+
+## 4. Configuration
+- **Environment Variables**: Use `stack.env` or Portainer environment variables for sensitive data.
+- **Parametrization**: Ideally, use `${PUID}`, `${PGID}`, and `${TZ}` variables to maintain portability across different user accounts.

SERVICE_SETUP_TEMPLATE.md

@@ -0,0 +1,44 @@
+# Service Setup Guide: [Service Name]
+
+This document outlines the end-to-end flow for deploying [Service Name] on Synology NAS using Portainer.
+
+## 1. Pre-Setup (Manual)
+These steps must be performed in the Synology DSM web interface before running any scripts.
+
+### Create Service User
+- [ ] Go to **Control Panel > User & Group**.
+- [ ] Click **Create**.
+- [ ] Name: `svc-[service-name]` (e.g., `svc-paperless`).
+- [ ] Group: `users`.
+- [ ] **Important**: Record the Username and Password.
+
+### Get User IDs (PUID/PGID)
+- [ ] Open a terminal (SSH) to your Synology NAS.
+- [ ] Run: `id svc-[service-name]`.
+- [ ] Record the `uid` (PUID) and `gid` (PGID).
+  - *Note: Typically UID is >1024 and GID is 100 or 65536.*
+
+## 2. Infrastructure Setup (Automated/Scripted)
+These steps prepare the folder structure and permissions.
+
+### Run Setup Script
+- [ ] Navigate to the service folder: `/volume1/docker/portainer-stacks/[service-folder]`.
+- [ ] Run the creation script:
+  ```bash
+  sudo bash create_[service]_folders.sh
+  ```
+- This script creates all necessary folders in `/volume1/docker/` and `/volume1/media/` and assigns ownership to the service user.
+
+## 3. Portainer Deployment
+Final steps to launch the service.
+
+### Configure Environment
+- [ ] Copy `stack.env.example` to `stack.env` (if applicable) or prepare variables.
+- [ ] Update `PUID` and `PGID` with the values obtained in Step 1.
+
+### Deploy Stack
+- [ ] Go to **Portainer > Stacks > Add stack**.
+- [ ] Name the stack (e.g., `[service-name]`).
+- [ ] Paste the content of `docker-compose.portainer.yml`.
+- [ ] Load environment variables from `stack.env`.
+- [ ] Click **Deploy the stack**.

filebrowser/create_filebrowser_folders.sh

@@ -13,6 +13,6 @@ chown 1042:65538 "${BASE}/config/settings.json"
 chmod 640 "${BASE}/config/settings.json"
 
 
-touch "${BASE}/database/filebroser.db"
+touch "${BASE}/database/filebrowser.db"
-chown 1042:65538 "${BASE}/database/filebroser.db"
+chown 1042:65538 "${BASE}/database/filebrowser.db"
-chmod 640 "${BASE}/database/filebroser.db"
+chmod 640 "${BASE}/database/filebrowser.db"

paperless/SETUP.md

@@ -0,0 +1,34 @@
+# Service Setup Guide: Paperless-ngx
+
+## 1. Pre-Setup (Manual)
+### Create Service User
+- [ ] **Manual**: Create a user named `svc-paperless` in Synology Control Panel.
+- [ ] **Manual**: Give this user read/write access to the `docker` and `media` shared folders.
+
+### Get User IDs
+- [ ] **Manual**: SSH into NAS and run `id svc-paperless`.
+- [ ] **Expected Output**: `uid=1036(svc-paperless) gid=65538(svc-group)`.
+- [ ] **Action**: Note these IDs for the `stack.env` file.
+
+## 2. Infrastructure Setup
+### Run Setup Script
+- [ ] **Action**: Run the setup script from this directory:
+  ```bash
+  sudo bash create_paperless_folders.sh
+  ```
+- **What it does**: 
+  - Creates `/volume1/docker/paperless/{data,media,consume,export}`.
+  - Creates `/volume1/docker/paperless/redisdata`.
+  - Sets ownership to `svc-paperless`.
+
+## 3. Portainer Deployment
+### Environment Variables
+- [ ] **Action**: Create or update `stack.env` in Portainer with:
+  - `PUID=1036` (Replace with your actual ID)
+  - `PGID=65538` (Replace with your actual ID)
+  - `PAPERLESS_SECRET_KEY` (Generate a long random string)
+
+### Deploy
+- [ ] **Action**: Create a new stack named `paperless` in Portainer.
+- [ ] **Action**: Paste `docker-compose.portainer.yml` and deploy.
+- [ ] **Verification**: Access Paperless at `http://[NAS_IP]:8010`.