Add comprehensive Uptime Kuma management documentation

Complete documentation for monitor and tag management workflows:

New documentation:
- README.md: Quick reference and complete workflow guide
- TAG_MANAGEMENT.md: Comprehensive tag management strategies
- tag_monitor.sh: Quick CLI script to tag monitors

Updated documentation:
- API.md: Added tag management section with quick reference

Coverage:
- Adding monitors with tags (complete workflow)
- Updating and deleting monitors
- Tag management strategies and patterns
- Common tagging patterns by service type
- Troubleshooting guide
- Best practices and maintenance tasks

All common operations are now documented with examples.

uptime-kuma/API.md

@@ -203,6 +203,45 @@ api.delete_monitor(1)
 api.disconnect()
 ```
 
+## Tag Management
+
+Tags help organize monitors by category. See [TAG_MANAGEMENT.md](TAG_MANAGEMENT.md) for comprehensive tag documentation.
+
+### Quick Tag Commands
+
+**Tag a new monitor:**
+```bash
+# After creating a monitor, tag it quickly
+./tag_monitor.sh MONITOR_ID TAG_ID [TAG_ID...]
+
+# Example: Tag monitor 15 as application + web
+./tag_monitor.sh 15 3 4
+```
+
+**View all tags:**
+```bash
+./check_tags.py
+```
+
+**Common Tag IDs:**
+- 1=hardware, 2=monitoring, 3=application, 4=web, 5=database
+- 6=media, 7=infrastructure, 8=storage, 9=virtualization, 10=vm
+
+**Full workflow for adding a tagged monitor:**
+```bash
+# 1. Add monitor and note the ID
+./manage_monitors.py add --name "New Service" --url "https://example.com"
+./manage_monitors.py list | grep "New Service"
+
+# 2. Tag it
+./tag_monitor.sh 16 3 4  # application + web
+
+# 3. Verify
+./check_tags.py | grep "New Service"
+```
+
+For detailed tagging strategies and workflows, see **[TAG_MANAGEMENT.md](TAG_MANAGEMENT.md)**.
+
 ## References
 
 - [Uptime Kuma API Keys Documentation](https://github.com/louislam/uptime-kuma/wiki/API-Keys)

uptime-kuma/README.md

@@ -0,0 +1,206 @@
+# Uptime Kuma Management
+
+Complete documentation for managing Uptime Kuma monitors and tags via CLI and API.
+
+## Quick Reference
+
+### Prerequisites
+```bash
+# Set credentials (add to ~/.bashrc for persistence)
+export UPTIME_KUMA_USERNAME="poprhythm"
+export UPTIME_KUMA_PASSWORD="your_password"
+```
+
+### Common Commands
+
+```bash
+# List all monitors
+./manage_monitors.py list
+
+# Add a monitor
+./manage_monitors.py add --name "Service" --url "https://example.com"
+
+# Update a monitor
+./manage_monitors.py update --id 123 --interval 120
+
+# Delete a monitor
+./manage_monitors.py delete --id 123
+
+# Tag a monitor
+./tag_monitor.sh 123 3 4  # Tag as application + web
+
+# View all tags
+./check_tags.py
+```
+
+## Documentation Files
+
+| File | Purpose |
+|------|---------|
+| **[SETUP.md](SETUP.md)** | Initial setup and installation |
+| **[API.md](API.md)** | Complete API usage and examples |
+| **[TAG_MANAGEMENT.md](TAG_MANAGEMENT.md)** | Comprehensive tag management guide |
+| **[TAG_SUMMARY.md](TAG_SUMMARY.md)** | Current tag schema and assignments |
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `manage_monitors.py` | Main CLI for monitor CRUD operations |
+| `tag_monitor.sh` | Quick script to tag monitors |
+| `check_tags.py` | View current tag assignments |
+| `add_tags.py` | Bulk tag assignment (requires editing) |
+| `fix_missing_tags.py` | Add specific tags to specific monitors |
+
+## Complete Workflow: Adding a New Monitor
+
+### Step 1: Add the Monitor
+```bash
+./manage_monitors.py add \
+  --name "New Service" \
+  --url "https://newservice.com" \
+  --type http \
+  --interval 60
+```
+
+### Step 2: Get Monitor ID
+```bash
+./manage_monitors.py list | grep "New Service"
+# Output: 16     New Service     http     https://newservice.com
+```
+
+### Step 3: Tag the Monitor
+```bash
+# Choose appropriate tags based on service type:
+# - Web service: 3 (application) + 4 (web)
+# - Database: 3 (application) + 5 (database)
+# - Storage: 7 (infrastructure) + 8 (storage)
+# - VM: 7 (infrastructure) + 10 (vm)
+
+./tag_monitor.sh 16 3 4
+```
+
+### Step 4: Verify
+```bash
+./check_tags.py | grep "New Service"
+# Should show the monitor with its tags
+```
+
+## Tag Reference
+
+| ID | Tag | Use For |
+|----|-----|---------|
+| 1 | hardware | Physical hardware monitoring |
+| 2 | monitoring | Monitoring systems |
+| 3 | application | Software applications |
+| 4 | web | Web services |
+| 5 | database | Database systems |
+| 6 | media | Media servers |
+| 7 | infrastructure | Core infrastructure |
+| 8 | storage | Storage systems |
+| 9 | virtualization | Virtualization platforms |
+| 10 | vm | Virtual machines |
+
+## Monitor Types
+
+| Type | Example URL | Use For |
+|------|-------------|---------|
+| `http` | `https://example.com` | HTTP/HTTPS endpoints |
+| `tcp` | `hostname:port` | TCP port checks |
+| `ping` | `192.168.1.1` | ICMP ping |
+| `dns` | `example.com` | DNS resolution |
+| `docker` | Container name | Docker container health |
+
+## Common Tagging Patterns
+
+```bash
+# Web application
+./manage_monitors.py add --name "GitLab" --url "https://gitlab.example.com"
+./tag_monitor.sh NEW_ID 3 4  # application + web
+
+# Database
+./manage_monitors.py add --name "PostgreSQL" --url "db.example.com:5432" --type tcp
+./tag_monitor.sh NEW_ID 3 5  # application + database
+
+# Storage/NAS
+./manage_monitors.py add --name "Storage" --url "nas.example.com" --type ping
+./tag_monitor.sh NEW_ID 7 8  # infrastructure + storage
+
+# Virtual Machine
+./manage_monitors.py add --name "VM Host" --url "vm.example.com" --type ping
+./tag_monitor.sh NEW_ID 7 10  # infrastructure + vm
+
+# Hardware monitoring
+./manage_monitors.py add --name "Server Fan" --url "..." --type mqtt
+./tag_monitor.sh NEW_ID 1 2  # hardware + monitoring
+```
+
+## Troubleshooting
+
+### Authentication Issues
+```bash
+# Check credentials are set
+echo $UPTIME_KUMA_USERNAME
+echo $UPTIME_KUMA_PASSWORD
+
+# If not set, export them
+export UPTIME_KUMA_USERNAME="poprhythm"
+export UPTIME_KUMA_PASSWORD="your_password"
+```
+
+### Monitor Not Found
+```bash
+# List all monitors to verify ID
+./manage_monitors.py list
+```
+
+### Tag Already Exists
+This is normal if you try to add a tag that's already assigned. It can be ignored.
+
+### SSL Certificate Warnings
+These warnings are expected for self-signed certificates and can be ignored. The scripts use `ssl_verify=False` to handle this.
+
+## Web UI
+
+Access the web interface at: **https://uptime.kolpacksoftware.com**
+
+- Filter by tags
+- View status pages
+- Manage notifications
+- Configure settings
+
+## Best Practices
+
+1. **Always tag new monitors** immediately after creation
+2. **Use 2-3 tags** per monitor for better organization
+3. **Document custom tags** if you add new tag types
+4. **Run audits** periodically with `check_tags.py`
+5. **Set credentials** persistently in your shell profile
+6. **Use descriptive names** for monitors (include service purpose)
+7. **Group related services** using consistent tagging
+
+## Getting Help
+
+- **Setup issues**: See [SETUP.md](SETUP.md)
+- **API questions**: See [API.md](API.md)
+- **Tag management**: See [TAG_MANAGEMENT.md](TAG_MANAGEMENT.md)
+- **Current tags**: See [TAG_SUMMARY.md](TAG_SUMMARY.md)
+- **Uptime Kuma docs**: https://github.com/louislam/uptime-kuma/wiki
+
+## Maintenance
+
+### Regular Tasks
+
+**Weekly:**
+- Review untagged monitors: `./check_tags.py | grep "No tags"`
+- Verify critical monitors are up
+
+**Monthly:**
+- Review and update monitor intervals
+- Clean up old/unused monitors
+- Verify tag schema still makes sense
+
+**As Needed:**
+- Update documentation when adding new tag types
+- Adjust check intervals based on service criticality
+- Review and optimize notification rules

uptime-kuma/TAG_MANAGEMENT.md

@@ -0,0 +1,264 @@
+# Tag Management Guide
+
+This guide covers managing tags and tag assignments in Uptime Kuma.
+
+## Overview
+
+Tags help organize and categorize monitors. Each monitor can have multiple tags, and you can filter monitors by tags in the web UI.
+
+## Current Tag Schema
+
+### Service Categories
+
+| Tag Name | Color | Use For |
+|----------|-------|---------|
+| `hardware` | 🔴 Red | Physical hardware (fans, sensors) |
+| `monitoring` | 🟠 Orange | Monitoring systems and health checks |
+| `application` | 🔵 Blue | Software applications and services |
+| `web` | 🔷 Cyan | Web services and HTTP endpoints |
+| `database` | 🟣 Purple | Database systems |
+| `media` | 🌸 Pink | Media servers (Plex, etc.) |
+| `infrastructure` | 🟢 Green | Core infrastructure components |
+| `storage` | 🟢 Light Green | Storage systems (NAS, file servers) |
+| `virtualization` | 🟦 Teal | Virtualization platforms (Proxmox) |
+| `vm` | 🔹 Blue Grey | Virtual machines |
+
+## Common Workflows
+
+### Adding a New Monitor with Tags
+
+**Step 1: Add the monitor**
+```bash
+export UPTIME_KUMA_USERNAME="your_username"
+export UPTIME_KUMA_PASSWORD="your_password"
+
+./manage_monitors.py add --name "New Service" --url "https://newservice.com" --type http
+```
+
+**Step 2: Note the monitor ID from the output or list**
+```bash
+./manage_monitors.py list
+# Note the ID of your new monitor (e.g., 15)
+```
+
+**Step 3: Add tags using Python API**
+```python
+#!/usr/bin/env python3
+from uptime_kuma_api import UptimeKumaApi
+
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+api.login("username", "password")
+
+# Add tags to monitor
+api.add_monitor_tag(tag_id=3, monitor_id=15, value='')  # application
+api.add_monitor_tag(tag_id=4, monitor_id=15, value='')  # web
+
+api.disconnect()
+```
+
+### Quick Tag Script
+
+Create a simple script to tag a new monitor:
+
+```bash
+#!/bin/bash
+# tag_monitor.sh - Quick script to tag a monitor
+# Usage: ./tag_monitor.sh MONITOR_ID TAG_ID [TAG_ID...]
+
+MONITOR_ID=$1
+shift
+
+python3 << EOF
+from uptime_kuma_api import UptimeKumaApi
+import os
+
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+api.login(os.getenv('UPTIME_KUMA_USERNAME'), os.getenv('UPTIME_KUMA_PASSWORD'))
+
+for tag_id in [${@}]:
+    try:
+        api.add_monitor_tag(tag_id=tag_id, monitor_id=${MONITOR_ID}, value='')
+        print(f"✓ Added tag {tag_id} to monitor ${MONITOR_ID}")
+    except Exception as e:
+        print(f"✗ Failed: {e}")
+
+api.disconnect()
+EOF
+```
+
+**Usage:**
+```bash
+# Tag monitor 15 as application + web
+export UPTIME_KUMA_USERNAME="poprhythm"
+export UPTIME_KUMA_PASSWORD="your_password"
+./tag_monitor.sh 15 3 4
+```
+
+### Viewing Tags on a Monitor
+
+```bash
+./check_tags.py
+```
+
+Or check a specific monitor:
+```python
+from uptime_kuma_api import UptimeKumaApi
+
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+api.login("username", "password")
+
+monitor = api.get_monitor(15)
+print(f"Tags: {monitor.get('tags', [])}")
+
+api.disconnect()
+```
+
+### Removing a Tag from a Monitor
+
+```python
+from uptime_kuma_api import UptimeKumaApi
+
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+api.login("username", "password")
+
+# Remove tag_id 3 from monitor 15
+api.delete_monitor_tag(tag_id=3, monitor_id=15, value='')
+
+api.disconnect()
+```
+
+### Adding New Tag Types
+
+If you need to create a new tag:
+
+```python
+from uptime_kuma_api import UptimeKumaApi
+
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+api.login("username", "password")
+
+# Create a new tag
+result = api.add_tag(name="production", color="#FF5722")
+print(f"Created tag with ID: {result['id']}")
+
+api.disconnect()
+```
+
+## Tag Assignment Patterns
+
+### By Service Type
+- **Web Services**: `application` + `web`
+- **Databases**: `application` + `database`
+- **Media Servers**: `application` + `media`
+- **Storage Systems**: `infrastructure` + `storage`
+- **Virtual Machines**: `infrastructure` + `vm`
+- **Hardware Monitoring**: `hardware` + `monitoring`
+- **Virtualization Platforms**: `infrastructure` + `virtualization`
+
+### By Environment (if needed)
+You can create additional tags for environments:
+```python
+api.add_tag(name="production", color="#4CAF50")
+api.add_tag(name="staging", color="#FFC107")
+api.add_tag(name="development", color="#2196F3")
+```
+
+### By Priority (if needed)
+```python
+api.add_tag(name="critical", color="#F44336")
+api.add_tag(name="high", color="#FF9800")
+api.add_tag(name="normal", color="#4CAF50")
+api.add_tag(name="low", color="#9E9E9E")
+```
+
+## Complete Example: Adding a New Service
+
+```bash
+# 1. Add the monitor
+./manage_monitors.py add \
+  --name "GitLab" \
+  --url "https://gitlab.example.com" \
+  --type http \
+  --interval 60
+
+# 2. List to get the ID
+./manage_monitors.py list | grep GitLab
+# Output: 16     GitLab     http     https://gitlab.example.com
+
+# 3. Tag it (using Python one-liner)
+python3 -c "
+from uptime_kuma_api import UptimeKumaApi
+import os
+api = UptimeKumaApi('https://uptime.kolpacksoftware.com', ssl_verify=False)
+api.login(os.getenv('UPTIME_KUMA_USERNAME'), os.getenv('UPTIME_KUMA_PASSWORD'))
+api.add_monitor_tag(tag_id=3, monitor_id=16, value='')  # application
+api.add_monitor_tag(tag_id=4, monitor_id=16, value='')  # web
+api.disconnect()
+print('Tagged successfully!')
+"
+
+# 4. Verify
+./check_tags.py | grep GitLab
+```
+
+## Tag Reference Quick Lookup
+
+| Tag ID | Tag Name | Common Use |
+|--------|----------|------------|
+| 1 | hardware | Server fans, sensors |
+| 2 | monitoring | Health checks |
+| 3 | application | Any software service |
+| 4 | web | HTTP/HTTPS services |
+| 5 | database | PostgreSQL, MySQL, CouchDB, etc. |
+| 6 | media | Plex, Jellyfin, etc. |
+| 7 | infrastructure | Core systems |
+| 8 | storage | NAS, file servers |
+| 9 | virtualization | Proxmox, ESXi |
+| 10 | vm | Virtual machine instances |
+
+## Best Practices
+
+1. **Consistent Naming**: Use lowercase for tag names
+2. **Multiple Tags**: Apply 2-3 relevant tags per monitor for better organization
+3. **Color Coding**: Use similar colors for related tags (all infrastructure tags are shades of green)
+4. **Document Custom Tags**: If you add custom tags, document them in this file
+5. **Tag on Creation**: Always tag new monitors immediately after creation
+6. **Regular Audits**: Run `check_tags.py` periodically to find untagged monitors
+
+## Troubleshooting
+
+### "Tag already exists" Error
+This means the tag is already assigned to the monitor. You can safely ignore this.
+
+### "Monitor not found"
+Double-check the monitor ID with `./manage_monitors.py list`.
+
+### Session Timeout
+If you're tagging many monitors, you may need to reconnect. The API session can timeout after several minutes of inactivity.
+
+### View All Tags
+```python
+from uptime_kuma_api import UptimeKumaApi
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+api.login("username", "password")
+tags = api.get_tags()
+for tag in tags:
+    print(f"ID {tag['id']}: {tag['name']} ({tag['color']})")
+api.disconnect()
+```
+
+## Scripts Available
+
+- `check_tags.py` - View all monitor tag assignments
+- `add_tags.py` - Bulk tag assignment (requires editing for new monitors)
+- `fix_missing_tags.py` - Add specific tags to specific monitors
+- `TAG_SUMMARY.md` - Current tag schema documentation
+
+## Web UI Management
+
+For one-off changes, the web UI is often easier:
+1. Go to https://uptime.kolpacksoftware.com
+2. Click on a monitor to edit it
+3. Scroll to the "Tags" section
+4. Add/remove tags as needed
+5. Click "Save"

uptime-kuma/tag_monitor.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Quick script to add tags to a monitor
+# Usage: ./tag_monitor.sh MONITOR_ID TAG_ID [TAG_ID...]
+#
+# Examples:
+#   ./tag_monitor.sh 15 3 4              # Tag monitor 15 as application + web
+#   ./tag_monitor.sh 20 7 8              # Tag monitor 20 as infrastructure + storage
+#   ./tag_monitor.sh 25 1 2              # Tag monitor 25 as hardware + monitoring
+#
+# Tag IDs:
+#   1=hardware  2=monitoring  3=application  4=web  5=database
+#   6=media  7=infrastructure  8=storage  9=virtualization  10=vm
+
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 MONITOR_ID TAG_ID [TAG_ID...]"
+    echo ""
+    echo "Tag IDs:"
+    echo "  1=hardware  2=monitoring  3=application  4=web  5=database"
+    echo "  6=media  7=infrastructure  8=storage  9=virtualization  10=vm"
+    echo ""
+    echo "Examples:"
+    echo "  $0 15 3 4    # Tag monitor 15 as application + web"
+    echo "  $0 20 7 8    # Tag monitor 20 as infrastructure + storage"
+    exit 1
+fi
+
+MONITOR_ID=$1
+shift
+TAG_IDS="$@"
+
+# Check for credentials
+if [ -z "$UPTIME_KUMA_USERNAME" ] || [ -z "$UPTIME_KUMA_PASSWORD" ]; then
+    echo "Error: Set UPTIME_KUMA_USERNAME and UPTIME_KUMA_PASSWORD environment variables"
+    exit 1
+fi
+
+# Convert tag IDs to Python list format
+TAG_LIST=$(echo "$TAG_IDS" | sed 's/ /, /g')
+
+python3 << EOF
+from uptime_kuma_api import UptimeKumaApi
+import os
+import sys
+
+api = UptimeKumaApi("https://uptime.kolpacksoftware.com", ssl_verify=False)
+
+try:
+    api.login(os.getenv('UPTIME_KUMA_USERNAME'), os.getenv('UPTIME_KUMA_PASSWORD'))
+
+    # Get monitor name for display
+    monitor = api.get_monitor(${MONITOR_ID})
+    print(f"Tagging monitor ${MONITOR_ID} ({monitor['name']})...")
+
+    for tag_id in [${TAG_LIST}]:
+        try:
+            api.add_monitor_tag(tag_id=tag_id, monitor_id=${MONITOR_ID}, value='')
+            print(f"  ✓ Added tag ID {tag_id}")
+        except Exception as e:
+            if 'already' in str(e).lower():
+                print(f"  - Tag ID {tag_id} already assigned")
+            else:
+                print(f"  ✗ Failed to add tag ID {tag_id}: {e}")
+
+    print("✅ Done!")
+
+except Exception as e:
+    print(f"Error: {e}", file=sys.stderr)
+    sys.exit(1)
+finally:
+    api.disconnect()
+EOF