feat: Enhance documentation and add porcelain mode support for improved automation in plex scripts

plex/plex-management.md

@@ -51,6 +51,37 @@ This script is part of a comprehensive Plex management suite:
 
 ## Enhanced Features
 
+### Smart Terminal Detection and Color Output
+
+The script includes intelligent terminal detection and color management:
+
+- **Automatic Color Detection**: Detects terminal capabilities and adjusts output accordingly
+- **Environment Variable Support**: Respects `NO_COLOR` environment variable for accessibility
+- **Porcelain Mode**: `--porcelain` or `-p` provides machine-readable output for automation
+- **ANSI Escape Handling**: Properly handles color codes when called from other scripts
+
+### System Integration and Automation
+
+- **update.sh Integration**: Automatically called during system updates with simple output mode
+- **Non-Interactive Operation**: Designed to work seamlessly when called from other scripts
+- **Service Presence Detection**: Gracefully handles systems without Plex installed
+- **Root User Prevention**: Explicitly prevents running as root for security
+
+### Environment Variables
+
+The script supports several environment variables for customization:
+
+```bash
+# Disable color output entirely
+NO_COLOR=1 ./plex.sh status
+
+# Force porcelain mode for machine-readable output
+./plex.sh --porcelain start
+
+# Check terminal capabilities
+TERM=dumb ./plex.sh status  # Forces simple output
+```
+
 ### Smart Service Management
 
 The enhanced script includes intelligent service operations:
@@ -92,7 +123,6 @@ Shows:
 - **Network Validation**: Verifies port availability and network configuration
 - **Recovery Capabilities**: Automatic recovery from common service issues
 
-
 ## Command Line Usage
 
 ### Basic Operations
@@ -111,37 +141,61 @@ Shows:
 ./plex.sh status
 ```
 
-### Advanced Options
+### Available Commands
+
+The script supports the following commands:
 
 ```bash
-# Enhanced status with detailed information
-./plex.sh status --verbose
+# Basic service operations
+./plex.sh start      # Start Plex Media Server
+./plex.sh stop       # Stop Plex Media Server  
+./plex.sh restart    # Restart Plex Media Server (also accepts 'reload')
+./plex.sh status     # Show detailed service status (also accepts 'info')
+./plex.sh logs       # Display recent Plex Media Server logs
+./plex.sh help       # Show help message (also accepts '--help' or '-h')
 
-# Force restart (ignores current state)
-./plex.sh restart --force
+# Logs command with options
+./plex.sh logs       # Display last 20 lines of Plex logs
+./plex.sh logs -n 50 # Display last 50 lines of Plex logs
+./plex.sh logs -f    # Follow logs in real-time
+./plex.sh logs --follow --lines 100  # Follow logs with custom line count
 
-# Safe stop with extended wait time
-./plex.sh stop --safe
+# Porcelain mode for machine-readable output
+./plex.sh --porcelain start          # Machine-readable service output
+./plex.sh --porcelain status         # Machine-readable status output
 
-# Start with configuration validation
-./plex.sh start --validate
+# Environment variable examples
+NO_COLOR=1 ./plex.sh status                    # Disable colors
+./plex.sh --porcelain start                    # Machine-readable output
 ```
 
+**Note**: The script automatically detects when it's being called from other scripts (like `update.sh`) and adjusts its output accordingly.
+
 ### Integration with Other Scripts
 
-The `plex.sh` script is designed to work seamlessly with other Plex management scripts:
+The `plex.sh` script is designed to work seamlessly with other Plex management scripts and system automation:
 
 ```bash
+# Used by update.sh during system updates (automatic porcelain output)
+./update.sh  # Automatically calls plex.sh --porcelain stop/start
+
 # Used by backup script for safe service management
 ./backup-plex.sh  # Automatically calls plex.sh stop/start
 
 # Used by recovery scripts for service control
 ./recover-plex-database.sh  # Uses plex.sh for service management
 
-# Used by testing scripts for service validation
-./integration-test-plex.sh  # Validates service operations
+# Manual integration with porcelain output
+./plex.sh --porcelain start  # For use in scripts/automation
 ```
 
+### Security and Safety Features
+
+- **Root Prevention**: Script refuses to run as root user for security
+- **Safe Defaults**: Uses conservative settings for service operations
+- **Error Handling**: Comprehensive error checking and reporting
+- **Graceful Degradation**: Works on systems without Plex installed
+
 ## Detailed Operation Steps
 
 ### Start Operation Process
@@ -191,14 +245,57 @@ The status command provides comprehensive system information:
 - **Recent Activity**: Latest log entries and system events
 - **Performance Metrics**: Uptime, resource usage, response times
 
+### Logs Operation Details
+
+The logs command provides flexible log viewing capabilities:
+
+```bash
+# Basic log viewing (last 20 lines)
+./plex.sh logs
+
+# Custom line count
+./plex.sh logs -n 50
+./plex.sh logs --lines 100
+
+# Real-time log following
+./plex.sh logs -f
+./plex.sh logs --follow
+
+# Combined options
+./plex.sh logs --follow --lines 50
+```
+
+**Logs Command Features:**
+
+- **Flexible Line Count**: Specify number of log lines to display (default: 20)
+- **Real-time Following**: Use `-f` or `--follow` to tail logs in real-time
+- **Systemd Integration**: Uses `journalctl` for reliable log access
+- **Porcelain Mode Support**: Works with `--porcelain` for script automation
+- **Error Handling**: Graceful handling when service is not available
+
+**Logs Command Options:**
+
+- `-n, --lines NUMBER`: Number of log lines to display (default: 20)
+- `-f, --follow`: Follow logs in real-time (like `tail -f`)
+- Can be combined with global `--porcelain` option for clean output
+
 ## Configuration and Dependencies
 
+### Environment Variable Configuration
+
+The script respects several environment variables for customization:
+
+- **`NO_COLOR`**: Set to `1` to disable all color output (accessibility compliance)
+- **`--porcelain`**: Command-line option to force machine-readable output (for automation)
+- **`TERM`**: Automatically detected; `dumb` terminals get simple output
+
 ### System Requirements
 
 - **Operating System**: systemd-based Linux distribution
-- **Permissions**: sudo access for systemctl operations
+- **Permissions**: sudo access for systemctl operations (script prevents running as root)
 - **Network**: Port 32400/tcp available for Plex communications
-- **Dependencies**: systemctl, curl (for network validation), ps (for process monitoring)
+- **Dependencies**: systemctl, basic shell utilities
+- **Service**: plexmediaserver.service (gracefully handles absence)
 
 ### Configuration Validation
 
@@ -218,6 +315,30 @@ The script integrates with the broader Plex management ecosystem:
 - **Testing Framework**: Utilized by integration tests for service validation
 - **Monitoring Systems**: Provides status information for monitoring dashboards
 
+### System Update Integration
+
+The script is designed to work seamlessly with system update processes:
+
+- **Automatic Integration**: Called by `update.sh` during system updates
+- **Service Management**: Safely stops Plex before package updates, restarts after completion
+- **Porcelain Mode**: Uses `--porcelain` for clean, log-friendly output
+- **Graceful Handling**: Properly handles systems without Plex installed
+- **Error Prevention**: Prevents interruption of package manager operations
+
+Example system update integration:
+
+```bash
+# In update.sh - automatically stops Plex before updates
+/home/acedanger/shell/plex/plex.sh --porcelain stop
+
+# Package updates occur here...
+
+# In update.sh - automatically starts Plex after updates
+/home/acedanger/shell/plex/plex.sh --porcelain start
+```
+
+This integration ensures that Plex databases and processes don't interfere with system package updates while maintaining service availability.
+
 ## Error Handling and Troubleshooting
 
 ### Common Issues and Solutions