From acb0069759462abcf67d1dc5fcb87c83c98ab2f9 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 30 Jul 2025 18:07:49 +0200
Subject: [PATCH] docs: Add comprehensive logging documentation to README

- Added configuration profile as the recommended method for unrestricted logging
- Documented all methods to view unredacted logs on macOS
- Added explanation of why Apple shows <private> in logs
- Included vtlog script usage examples
- Reorganized logging section for better clarity
---
 README.md | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e0d3f785..d4e72d95 100644
--- a/README.md
+++ b/README.md
@@ -971,20 +971,42 @@ VibeTunnel uses the following bundle identifiers:
 
 To see full log details for debugging, you have several options:
 
-1. **Use the vtlog script with sudo** (reveals private data):
+1. **Install the Configuration Profile** (Recommended - easiest method):
    ```bash
-   sudo ./scripts/vtlog.sh --info
+   # Install the logging configuration profile
+   open apple/logging/VibeTunnel-Logging.mobileconfig
+   
+   # This enables debug logging for all VibeTunnel components
+   # To remove later: System Settings → Privacy & Security → Profiles
    ```
 
-2. **Configure passwordless sudo** for the log command:
+2. **Use the vtlog script** (convenient log viewer):
+   ```bash
+   # View recent logs (requires configuration profile or sudo)
+   ./scripts/vtlog.sh
+   
+   # Follow logs in real-time
+   ./scripts/vtlog.sh -f
+   
+   # Show only errors
+   ./scripts/vtlog.sh -e
+   
+   # Filter by category
+   ./scripts/vtlog.sh -c ServerManager
+   ```
+
+3. **Configure passwordless sudo** (alternative for vtlog with -p flag):
    ```bash
    # Add to sudoers (replace 'yourusername' with your actual username)
    sudo visudo
    # Add this line:
    yourusername ALL=(ALL) NOPASSWD: /usr/bin/log
+   
+   # Then use vtlog with private flag
+   ./scripts/vtlog.sh -p
    ```
 
-3. **Enable private data logging** using a plist file (recommended):
+4. **Enable private data logging** using a plist file (alternative):
    ```bash
    # Create the plist to enable private data for VibeTunnel
    sudo mkdir -p /Library/Preferences/Logging/Subsystems
@@ -1000,6 +1022,10 @@ To see full log details for debugging, you have several options:
    EOF
    ```
 
+### Why Logs Show `<private>`
+
+Apple redacts dynamic values in logs by default to protect user privacy. This prevents accidental logging of passwords, tokens, or personal information. Our configuration profile or the methods above enable full visibility for development and debugging.
+
 For more detailed information about logging privacy and additional methods, see [apple/docs/logging-private-fix.md](apple/docs/logging-private-fix.md).
 
 ## Contributing