Docs

README.md

@@ -2,6 +2,28 @@
 
 Automated setup scripts for configuring an Apple Silicon Mac Mini as a home server with native macOS applications.
 
+## TL;DR - Quick Start
+
+**What this does**: Turns a fresh Mac Mini into a configured home server with Plex, BitTorrent, Dropbox sync, and remote access.
+
+**Prerequisites** (5 minutes):
+
+1. Install 1Password CLI: `brew install 1password-cli && op signin`
+2. Generate SSH keys: `ssh-keygen -t ed25519`
+3. Copy `config/config.conf.template` to `config/config.conf` and set your `SERVER_NAME`
+4. Create these 1Password items: "operator", "TimeMachine", "Plex NAS", "Apple", "OpenSubtitles"
+
+**Setup** (15 minutes):
+
+1. **On dev Mac**: `./prep-airdrop.sh` (creates deployment package)
+2. **AirDrop** the generated folder to your Mac Mini
+3. **On Mac Mini desktop** (not SSH): `cd ~/Downloads/MACMINI-setup && ./first-boot.sh`
+4. **Reboot** and login as operator for automatic final setup
+
+**Result**: Fully configured server accessible at `your-server-name.local` with web interfaces for all services.
+
+📖 **Need details?** See [Prerequisites](docs/prerequisites.md) and [Environment Variables](docs/environment-variables.md) for complete guidance.
+
 ## Project Overview
 
 This project provides a complete automation framework for setting up an Apple Silicon Mac Mini server that functions as:
@@ -77,7 +99,7 @@ This project provides a complete automation framework for setting up an Apple Si
 
 The setup process consists of two main phases:
 
-1. **Base System Setup** (`airdrop-prep.sh` + `first-boot.sh`)
+1. **Base System Setup** (`prep-airdrop.sh` + `first-boot.sh`)
 
    - System configuration and hardening
    - User account management
@@ -96,38 +118,58 @@ The setup process consists of two main phases:
 
 - Apple Silicon Mac Mini with fresh macOS installation
 - Development Mac with:
-  - 1Password CLI installed and authenticated
-  - SSH keys generated (`~/.ssh/id_ed25519.pub`)
-  - Required 1Password vault items (see [AirDrop Prep Instructions](docs/setup/prep-airdrop.md))
+  - **1Password CLI installed and authenticated** (`brew install 1password-cli && op signin`)
+  - **SSH keys generated** (`~/.ssh/id_ed25519` and `~/.ssh/id_ed25519.pub`)
+  - **Required 1Password vault items**: operator, TimeMachine, Plex NAS, Apple ID, OpenSubtitles
+  - **Core tools**: `jq`, `openssl` (pre-installed on macOS)
+  - **Valid configuration**: Copy `config/config.conf.template` to `config/config.conf` and customize
+
+**📖 See [Prerequisites Guide](docs/prerequisites.md) for complete setup requirements and validation commands**
 
 > **Compatibility Note**: This automation is designed and tested for **macOS 15.x on Apple Silicon**. It may work on earlier macOS versions or Intel-based Macs, but compatibility is not guaranteed and has not been tested.
 
 ### Setup Process
 
-1. **Prepare setup package** on your development Mac:
+1. **Prepare deployment package** on your development Mac:
 
    ```bash
    ./prep-airdrop.sh
    ```
 
+   This comprehensive script:
+   - Retrieves credentials from 1Password and transfers them securely via external keychain
+   - Creates hardware fingerprint validation to prevent wrong-machine execution
+   - Configures WiFi credentials (offers Migration Assistant or script-based options)
+   - Generates deployment manifest for package validation
+   - Processes all configuration files with environment-specific substitutions
+
 2. **Transfer to Mac Mini** via AirDrop (entire setup folder)
 
    > You can use [airdrop-cli](https://github.com/vldmrkl/airdrop-cli) (requires Xcode) to AirDrop files from the command line!
    > Install: (`brew install --HEAD vldmrkl/formulae/airdrop-cli`)
 
-3. **Run initial setup** on Mac Mini (**requires local desktop session**):
+3. **Run system provisioning** on Mac Mini (**requires local desktop session**):
 
    ```bash
    cd ~/Downloads/MACMINI-setup # default name
    ./first-boot.sh
    ```
 
-   > **Important**: Must be run from the Mac Mini's local desktop session (not via SSH). The script requires GUI access for System Settings automation, AppleScript dialogs, and user account configuration.
+   > **Critical**: Must be run from the Mac Mini's local desktop session (Terminal.app) - CANNOT run via SSH. The script performs comprehensive system provisioning including user account creation, credential import, FileVault management, and configuration of 15+ system modules.
+
+   This script performs:
+   - Hardware fingerprint validation and FileVault compatibility checks
+   - Operator user account creation with automatic login configuration
+   - SSH key deployment and credential import from external keychain
+   - Multi-phase system configuration via specialized modules
+   - Comprehensive error collection and end-of-run validation
 
 4. **Complete operator setup** after reboot (see [Operator Setup](docs/operator.md))
 
 ## Documentation
 
+- **[Prerequisites Guide](docs/prerequisites.md)** - Complete setup requirements and validation
+- **[Environment Variables](docs/environment-variables.md)** - Comprehensive customization reference
 - [AirDrop Prep Instructions](docs/setup/prep-airdrop.md) - Preparing the setup package
 - [First Boot Instructions](docs/setup/first-boot.md) - Running the initial setup
 - [Operator Setup](docs/operator.md) - Post-reboot configuration
@@ -140,14 +182,12 @@ The setup process consists of two main phases:
 ├── README.md                   # This file
 ├── prep-airdrop.sh             # Setup package preparation (primary entry point)
 ├── app-setup/                  # Application setup scripts
-│   ├── config/                # Application-specific configuration
-│   │   ├── plex_nas.conf      # Plex NAS configuration
-│   │   ├── rclone.conf        # rclone OAuth configuration
-│   │   └── dropbox_sync.conf  # Dropbox sync settings
 │   ├── templates/             # Runtime script templates
 │   │   ├── mount-nas-media.sh # SMB mount script template
-│   │   ├── start-plex.sh # Plex startup wrapper template
-│   │   └── start-rclone.sh    # rclone sync script template
+│   │   ├── start-plex.sh      # Plex startup wrapper template
+│   │   ├── start-rclone.sh    # rclone sync script template
+│   │   ├── transmission-done.sh # Transmission completion script
+│   │   └── transmission-done-template.sh # Transmission completion template
 │   ├── plex-setup.sh          # Plex Media Server setup
 │   ├── rclone-setup.sh        # Dropbox sync setup
 │   ├── transmission-setup.sh   # BitTorrent client with GUI automation
@@ -161,8 +201,12 @@ The setup process consists of two main phases:
 │       └── operator-first-login.sh # Operator account customization (automatic via LaunchAgent)
 ├── config/                     # Configuration files
 │   ├── config.conf.template   # Configuration template
+│   ├── config.conf            # Active configuration file
 │   ├── formulae.txt           # Homebrew formulae list
-│   └── casks.txt              # Homebrew casks list
+│   ├── casks.txt              # Homebrew casks list
+│   ├── logrotate.conf         # Log rotation configuration
+│   ├── iterm2.plist           # iTerm2 profile settings
+│   └── Orangebrew.terminal    # Terminal.app profile
 └── docs/                       # Documentation
     ├── setup/                 # Setup documentation
     │   ├── prep-airdrop.md

app-setup/filebot-setup.sh

@@ -9,9 +9,10 @@
 # - OpenSubtitles configuration for subtitle downloading
 # - Integration with transmission and media pipeline
 #
-# Usage: ./filebot-setup.sh [--force] [--license-file PATH]
+# Usage: ./filebot-setup.sh [--force] [--license-file PATH] [--password PASSWORD]
 #   --force: Skip all confirmation prompts
 #   --license-file: Override license file path (default: from config)
+#   --password: Administrator password for system configuration
 #
 # Author: Claude
 # Version: 1.0
@@ -98,7 +99,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     *)
       echo "❌ Unknown option: $1"
-      echo "Usage: $0 [--force] [--license-file PATH]"
+      echo "Usage: $0 [--force] [--license-file PATH] [--password PASSWORD]"
       exit 1
       ;;
   esac

app-setup/plex-setup.sh

@@ -8,7 +8,7 @@
 # - Configuration migration from existing Plex server
 # - Auto-start configuration
 #
-# Usage: ./plex-setup.sh [--force] [--migrate] [--skip-migration] [--skip-mount] [--server-name NAME] [--migrate-from HOST] [--custom-port PORT] [--password PASSWORD]
+# Usage: ./plex-setup.sh [--force] [--clean] [--migrate] [--skip-migration] [--skip-mount] [--server-name NAME] [--migrate-from HOST] [--custom-port PORT] [--password PASSWORD]
 #   --force: Skip all confirmation prompts
 #   --clean: Stop and remove existing Plex Media Server if found
 #   --migrate: Skip initial migration prompt (for orchestrator use)

app-setup/transmission-setup.sh

@@ -1,17 +1,32 @@
 #!/usr/bin/env bash
 #
-# transmission-setup.sh - Transmission BitTorrent client setup script for Mac Mini server
+# transmission-setup.sh - Transmission BitTorrent Client with Complete GUI Automation
 #
-# This script sets up Transmission on macOS with:
-# - Native Transmission installation via Homebrew cask
-# - Complete preferences configuration via defaults commands
-# - Download paths matching original user configuration
-# - Remote access (RPC) configuration
-# - Auto-start configuration via LaunchAgent for operator
+# This script provides comprehensive Transmission setup including:
+# - Native Transmission installation via Homebrew cask with version detection
+# - ~95% GUI preference automation using verified plist keys only
+# - Magnet link handler configuration via Launch Services integration
+# - Media pipeline integration with download paths and completion scripts
+# - RPC web interface with authentication and remote access at port 19091
+# - LaunchAgent configuration for automatic startup with operator login
+# - Network configuration: peer settings, encryption, port mapping, blocklist
+#
+# SYSTEM INTEGRATION:
+# - Configures Transmission as default magnet link application
+# - Creates FileBot integration completion script template
+# - Integrates with rclone sync directory for automated processing
+# - Supports complete media pipeline: Catch → Transmission → FileBot → Plex
+#
+# PREFERENCES AUTOMATED (~95% GUI coverage):
+# - Download management: paths, seeding limits, completion handling
+# - Network settings: fixed peer port (40944), UPnP, µTP protocol
+# - UI settings: auto-resize, confirmation prompts, watch folder
+# - Security: RPC authentication, whitelist configuration
+# - File handling: delete original torrents, download confirmation
 #
 # Usage: ./transmission-setup.sh [--force] [--rpc-password PASSWORD]
 #   --force: Skip all confirmation prompts
-#   --rpc-password: Override RPC password (default: from config or hostname)
+#   --rpc-password: Override RPC web interface password (default: auto-generated from hostname)
 #
 # Author: Claude
 # Version: 1.0

docs/apps/plex-setup-README.md

@@ -364,4 +364,91 @@ rm -f ~/Library/LaunchAgents/com.plexapp.plexmediaserver.plist
 ./app-setup/plex-setup.sh
 ```
 
+## Post-Setup Configuration
+
+**⚠️ Important**: After successful Plex setup, you should review and configure your Plex server settings to match your preferences. The setup script automates the basic installation and media access, but many personalization settings require manual configuration.
+
+### Required Manual Configuration
+
+Access your Plex server at `http://your-server.local:32400` and review these settings:
+
+#### **Server Settings** → **General**
+
+- **Server name**: Verify the automatically configured name
+- **Language and region**: Set your preferred language and country
+- **Remote access**: Configure if you need external access to your server
+
+#### **Server Settings** → **Library**
+
+- **Add media libraries**: Point to your mounted media directories (`~/.local/mnt/Media/...`)
+- **Library naming**: Customize library names (Movies, TV Shows, Music, etc.)
+- **Scanner settings**: Configure metadata agents and scanner options
+- **Artwork and metadata**: Set preferred metadata and artwork sources
+
+#### **Server Settings** → **Network**
+
+- **Remote access**: Enable/disable and configure port forwarding if needed
+- **LAN networks**: Add your local network ranges for better security
+- **Advanced networking**: Configure if you have complex network requirements
+
+#### **Server Settings** → **Transcoder**
+
+- **Transcoder quality**: Set hardware acceleration preferences (Apple Silicon supports hardware transcoding)
+- **Background transcoding**: Configure optimization schedules
+- **Bandwidth limits**: Set streaming quality limits if needed
+
+#### **Server Settings** → **Scheduled Tasks**
+
+- **Library maintenance**: Configure automatic library updates
+- **Media optimization**: Set up background video optimization
+- **Backup schedules**: Configure automatic database backups
+
+### User-Specific Preferences
+
+#### **Account Settings**
+
+- **Privacy settings**: Configure data sharing and analytics preferences
+- **Sharing settings**: Set up user access and sharing permissions
+- **Online media sources**: Configure or disable online content integration
+
+#### **Playback Settings**
+
+- **Quality settings**: Default streaming quality for different connection types
+- **Subtitle settings**: Default subtitle preferences and fonts
+- **Audio settings**: Default audio track preferences
+
+### Optional Advanced Configuration
+
+#### **Webhooks and Notifications**
+
+- **Plex webhook**: Configure external service integrations
+- **Mobile notifications**: Set up push notifications for mobile apps
+
+#### **DLNA and External Players**
+
+- **DLNA server**: Enable if you have DLNA devices on your network
+- **External player support**: Configure for specialized media players
+
+#### **Media Scanner Settings**
+
+- **File detection**: Configure how often libraries are scanned for new content
+- **Metadata refresh**: Set automatic metadata update intervals
+
+### Integration with Media Pipeline
+
+If you're using the complete media pipeline (Transmission → FileBot → Plex), verify:
+
+1. **Media library paths** point to the final processed media locations
+2. **FileBot output directories** match Plex library scan paths
+3. **Transmission completion scripts** are properly moving files to Plex-monitored directories
+
+### Testing Your Configuration
+
+After configuration:
+
+1. **Add test content** to verify library scanning works
+2. **Test playback** on different devices to verify transcoding
+3. **Check mobile access** if remote access is enabled
+4. **Verify media pipeline** by downloading test content through the full workflow
+
 The script integrates with the server's configuration system and follows the administrator-setup, operator-execution model used throughout the project.