cal/claude-home
1
0
Fork 0
Code Issues 6 Pull Requests 4 Actions Packages Projects Releases Wiki Activity
a35891b565
claude-home/CLAUDE.md
Cal Corum a35891b565 Add Uptime Kuma service monitoring on LXC 227 
Deploy Uptime Kuma for centralized service uptime monitoring at
https://status.manticorum.com. Proxmox LXC 227 (10.10.0.227) running
Ubuntu 22.04 with Docker. Updated monitoring documentation, CLAUDE.md
context loading rules, and server-configs host inventory.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 22:18:51 -06:00

20 KiB
Raw Blame History

Home Lab Documentation System

Core Instructions

  • You do not need to ask for permission to run tests. You always have permission.
  • When new code is written, include checking for imports as part of the code review. We should never get NameErrors during testing.
  • Always ask clarifying questions for complex configurations or multi-step tasks.
  • Do what has been asked; nothing more, nothing less.
  • If creating a temporary file will help achieve your goal, please create the file in the .claude/tmp/ directory and clean up when you're done.
  • Prefer editing an existing file to creating a new one.
  • Following a complex task or series of tasks, prompt the user to save any key learnings from the session.
  • Documentation Maintenance Reminder: At the end of coding sessions, proactively ask: "Should I update our documentation to reflect the changes we made today?" Focus on CONTEXT.md files, troubleshooting guides, and any new patterns discovered.
  • Context Window Management: When approaching 25% context window remaining, prioritize documentation updates before auto-summarization occurs. Ask: "We're approaching context limits - should I update our documentation now to capture today's work before we lose context?"

Automatic Context Loading Rules

Technology-First Loading Rules

When working with specific technologies, automatically load their dedicated context:

Tdarr Keywords

  • "tdarr", "transcode", "ffmpeg", "gpu transcoding", "nvenc", "scheduler", "api"
    • Load: tdarr/CONTEXT.md (technology overview and patterns)
    • Load: tdarr/troubleshooting.md (error handling and debugging)
    • If working in /tdarr/scripts/: Load tdarr/scripts/CONTEXT.md (script-specific documentation)
    • Note: Gaming-aware scheduling system with configurable time windows available
    • Note: Comprehensive API monitoring available via tdarr_monitor.py with dataclass-based status tracking

Docker Keywords

  • "docker", "container", "image", "compose", "kubernetes", "k8s", "dockerfile", "podman"
    • Load: docker/CONTEXT.md (technology overview and patterns)
    • Load: docker/troubleshooting.md (error handling and debugging)
    • If working in /docker/scripts/: Load docker/scripts/CONTEXT.md (script-specific documentation)

VM Management Keywords

  • "virtual machine", "vm", "proxmox", "kvm", "hypervisor", "guest", "virtualization"
    • Load: vm-management/CONTEXT.md (technology overview and patterns)
    • Load: vm-management/troubleshooting.md (error handling and debugging)
    • If working in /vm-management/scripts/: Load vm-management/scripts/CONTEXT.md (script-specific documentation)

Networking Keywords

  • "network", "nginx", "proxy", "load balancer", "dns", "port", "firewall", "ssh", "ssl", "tls", "npm", "nginx proxy manager", "reverse proxy", "pihole", "pi-hole", "orbital sync", "dns ha", "high availability dns", "dns failover"
    • Load: networking/CONTEXT.md (technology overview and patterns)
    • Load: networking/troubleshooting.md (error handling and debugging)
    • If working in /networking/scripts/: Load networking/scripts/CONTEXT.md (script-specific documentation)
    • If "pihole" or "pi-hole" mentioned: Load networking/pihole-ha-setup.md (dual Pi-hole HA architecture)
    • Note: Comprehensive NPM configuration documented in server-configs/networking/nginx-proxy-manager-pihole.md
    • Note: Dual Pi-hole deployment: Primary (10.10.0.16), Secondary (10.10.0.226)
    • Note: Orbital Sync handles Pi-hole → Pi-hole synchronization (5-minute interval)
    • Note: NPM DNS sync script updates both Pi-holes hourly with proxy host entries

Monitoring Keywords

  • "monitoring", "alert", "notification", "discord", "health check", "status", "uptime", "uptime kuma", "uptime-kuma", "status page", "windows reboot", "system monitor", "gpu monitor", "nvidia monitor", "driver monitor"
    • Load: monitoring/CONTEXT.md (technology overview and patterns)
    • Load: monitoring/troubleshooting.md (error handling and debugging)
    • If working in /monitoring/scripts/: Load monitoring/scripts/CONTEXT.md (script-specific documentation)
    • Note: Uptime Kuma centralized service monitoring on LXC 227 (10.10.0.227)
    • Note: Status page at https://status.manticorum.com (internal: http://10.10.0.227:3001)
    • Note: Windows desktop monitoring with Discord notifications available
    • Note: Comprehensive Tdarr API monitoring with dataclass-based status tracking
    • Note: Jellyfin GPU monitoring with auto-restart (jellyfin_gpu_monitor.py)
    • Note: NVIDIA driver update monitoring with weekly checks (nvidia_update_checker.py)

Productivity Keywords

  • "task", "todo", "productivity", "task manager", "brain dump", "focus", "adhd", "task tracking", "context switch", "task dashboard", "n8n", "workflow", "automation", "webhook", "integration", "ko-fi", "payment", "shop order"
    • Load: productivity/CONTEXT.md (technology overview and patterns)
    • Load: productivity/troubleshooting.md (error handling and debugging)
    • If "n8n" mentioned: Load productivity/n8n/CONTEXT.md (n8n-specific documentation)
    • If "ko-fi" mentioned: Load productivity/n8n/workflows/kofi-paper-dynasty.md (Ko-fi integration workflow)
    • Note: ADHD-optimized task management with persistent terminal dashboard
    • Note: Zero-friction brain dump capture to prevent context switching
    • Note: n8n workflow automation platform at n8n.manticorum.com (LXC 210)
    • Note: Ko-fi → Paper Dynasty integration for automated pack distribution
    • Location: Task manager at ~/.claude/tools/task-manager/, n8n at LXC 210 (10.10.0.210)

OpenClaw Keywords

  • "openclaw", "ai assistant", "personal assistant", "minimax", "autonomous agent", "agent skills"
    • Load: productivity/openclaw/CONTEXT.md (technology overview and patterns)
    • Load: productivity/openclaw/troubleshooting.md (error handling and debugging)
    • Note: Personal AI assistant on LXC 224 with MiniMax M2.1 and Discord integration
    • Location: LXC 224 (10.10.0.224), gateway at http://10.10.0.224:18789

Media Server Keywords

  • "jellyfin", "plex", "emby", "media server", "streaming", "watchstate", "watch history", "nvidia driver", "gpu transcoding", "nvenc"
    • Load: media-servers/CONTEXT.md (technology overview and patterns)
    • If "jellyfin" mentioned: Load media-servers/jellyfin-ubuntu-manticore.md (Jellyfin-specific setup)
    • Note: Jellyfin on ubuntu-manticore (10.10.0.226) with GPU transcoding
    • Note: Shares GPU resources with Tdarr - coordinate concurrent usage
    • Note: NVIDIA driver packages held to prevent auto-updates; weekly update monitoring via Discord
    • Note: GPU health monitoring every 5 minutes with auto-restart capability

Media Tools Keywords

  • "media download", "video download", "yt-dlp", "playwright", "pokeflix", "streaming scraper", "web scraping", "media archival"
    • Load: media-tools/CONTEXT.md (technology overview and patterns)
    • Load: media-tools/troubleshooting.md (error handling and debugging)
    • If working in /media-tools/scripts/: Load media-tools/scripts/CONTEXT.md (script-specific documentation)
    • Note: Browser automation with Playwright for JavaScript-heavy streaming sites
    • Note: yt-dlp integration for video downloading
    • Note: Resumable downloads with JSON state persistence
    • Note: Anti-bot handling with realistic browser behaviors

Gaming Keywords

  • "gaming", "steam", "proton", "steam tinker launch", "stl", "ready or not", "gamescope", "gamemode", "dxvk", "wine", "windows games", "linux gaming"
    • Load: gaming/CONTEXT.md (technology overview and patterns)
    • Load: gaming/troubleshooting.md (error handling and debugging)
    • If working in /gaming/scripts/: Load gaming/scripts/CONTEXT.md (script-specific documentation)
    • Note: Steam Tinker Launch for advanced Proton configuration
    • Note: Ready or Not (Game ID: 1144200) specific configs available
    • Note: NVIDIA GPU optimizations with NVAPI, DXVK, GameScope
    • Note: Config location: ~/.config/steamtinkerlaunch/
    • Note: 12 gaming scripts for RON setup, STL logs, Proton testing

Server Configs Keywords

  • "server config", "lxc config", "docker compose deploy", "infrastructure config", "gitea", "n8n config", "foundry config", "home assistant config", "config sync"
    • Load: server-configs/README.md (technology overview)
    • Note: Version-controlled infrastructure configurations for all hosts
    • Note: Centralized Docker Compose and VM/LXC configuration management
    • Note: sync-configs.sh for automated config deployment and synchronization
    • Note: Covers Proxmox LXCs, VMs, and physical servers (ubuntu-manticore)
    • Note: Services include: Gitea, n8n, Home Assistant, Foundry VTT, OpenClaw, Uptime Kuma, Discord bots, databases

Databases Keywords

  • "database", "sql", "postgres", "mysql", "redis", "mongodb", "db optimization", "query performance", "database backup", "connection pooling", "schema migration"
    • Load: databases/CONTEXT.md (technology overview and patterns)
    • Load: databases/troubleshooting.md (error handling and debugging)
    • Note: Database design patterns (normalization, indexing, schema versioning)
    • Note: Performance optimization (connection pooling, query optimization, caching)
    • Note: Backup and recovery strategies (point-in-time recovery, replication)
    • Note: Security and access control (privilege management, encryption, audit logging)

Directory Context Triggers

When working in specific directories:

Technology directories (/tdarr/, /docker/, /vm-management/, /networking/, /monitoring/, /productivity/, /media-servers/)

  • Load: {technology}/CONTEXT.md (technology overview)
  • Load: {technology}/troubleshooting.md (debugging info)

Script subdirectories (/tdarr/scripts/, /docker/scripts/, etc.)

  • Load: {technology}/CONTEXT.md (parent technology context)
  • Load: {technology}/scripts/CONTEXT.md (script-specific context)
  • Load: {technology}/troubleshooting.md (debugging info)
  • Context: Active operational scripts - treat as production code

Legacy directories (for backward compatibility)

  • /scripts/tdarr/ → Load Tdarr context files
  • /scripts/monitoring/ → Load Monitoring context files
  • /patterns/, /examples/, /reference/ → Load as before until migration complete

File Extension Triggers

For programming languages, load general development context:

Python (.py, .pyx, .pyi)

  • Load: development/python-CONTEXT.md (Python patterns and best practices)
  • If Django/Flask detected: Load development/web-frameworks-CONTEXT.md
  • If requests/httpx detected: Load development/api-clients-CONTEXT.md

JavaScript/Node.js (.js, .mjs, .ts)

  • Load: development/nodejs-CONTEXT.md (Node.js patterns and best practices)
  • If package.json exists: Load development/package-management-CONTEXT.md

Shell Scripts (.sh, .bash, .zsh)

  • Load: development/bash-CONTEXT.md (Bash scripting patterns)
  • If systemd mentioned: Load development/service-management-CONTEXT.md

Troubleshooting Keywords

For troubleshooting scenarios, always load both context and troubleshooting files:

General Troubleshooting Keywords

  • "shutdown", "stop", "emergency", "reset", "recovery", "crash", "broken", "not working", "error", "issue", "problem", "debug", "troubleshoot", "fix"
    • If Tdarr context detected: Load tdarr/CONTEXT.md AND tdarr/troubleshooting.md
    • If Docker context detected: Load docker/CONTEXT.md AND docker/troubleshooting.md
    • If VM context detected: Load vm-management/CONTEXT.md AND vm-management/troubleshooting.md
    • If Network context detected: Load networking/CONTEXT.md AND networking/troubleshooting.md
    • If Monitoring context detected: Load monitoring/CONTEXT.md AND monitoring/troubleshooting.md
    • If Productivity context detected: Load productivity/CONTEXT.md AND productivity/troubleshooting.md

Specific Tdarr Troubleshooting Keywords

  • "forEach error", "staging timeout", "gaming detection", "plugin error", "container stop", "node disconnect", "cache cleanup", "shutdown tdarr", "stop tdarr", "emergency tdarr", "reset tdarr"
    • Load: tdarr/CONTEXT.md (technology overview)
    • Load: tdarr/troubleshooting.md (specific solutions including Emergency Recovery section)
    • If working in /tdarr/scripts/: Load tdarr/scripts/CONTEXT.md

Priority Rules

  1. File extension triggers take highest priority
  2. Directory context takes second priority
  3. Keyword triggers are additive and load supplementary context
  4. If multiple technologies detected, load all relevant patterns
  5. Always prefer specific over general (e.g., vuejs/ over nodejs/)

Context Loading Behavior

  • Technology context first: Load CONTEXT.md for overview and patterns
  • Troubleshooting context: ALWAYS load troubleshooting.md for error scenarios and emergency procedures
  • Script-specific context: Load scripts/CONTEXT.md when working in script directories
  • Examples last: Load examples for implementation details
  • Critical rule: For any troubleshooting scenario, load BOTH context and troubleshooting files to ensure complete information
  • Maximum of 3-4 documentation files per trigger to maintain efficiency while ensuring comprehensive coverage

Documentation Structure

/tdarr/                    # Tdarr transcoding automation
  ├── CONTEXT.md           # Technology overview, patterns, best practices
  ├── troubleshooting.md   # Error handling and debugging
  ├── examples/            # Working configurations and templates
  └── scripts/             # Active automation scripts
      ├── CONTEXT.md       # Script-specific documentation
      ├── monitoring.py    # Comprehensive API monitoring with dataclasses
      └── scheduler.py     # Gaming-aware scheduling system

/docker/                   # Container orchestration and management
  ├── CONTEXT.md           # Technology overview, patterns, best practices
  ├── troubleshooting.md   # Error handling and debugging
  ├── examples/            # Working configurations and templates
  └── scripts/             # Active automation scripts
      └── CONTEXT.md       # Script-specific documentation

/vm-management/            # Virtual machine operations
  ├── CONTEXT.md           # Technology overview, patterns, best practices
  ├── troubleshooting.md   # Error handling and debugging
  ├── examples/            # Working configurations and templates
  └── scripts/             # Active automation scripts
      └── CONTEXT.md       # Script-specific documentation

/networking/               # Network configuration and SSH management
  ├── CONTEXT.md           # Technology overview, patterns, best practices
  ├── troubleshooting.md   # Error handling and debugging
  ├── examples/            # Working configurations and templates
  └── scripts/             # Active automation scripts
      └── CONTEXT.md       # Script-specific documentation

/monitoring/               # System monitoring and alerting
  ├── CONTEXT.md           # Technology overview, patterns, best practices
  ├── troubleshooting.md   # Error handling and debugging
  ├── examples/            # Working configurations and templates
  └── scripts/             # Active automation scripts
      ├── CONTEXT.md       # Script-specific documentation
      ├── jellyfin_gpu_monitor.py      # Jellyfin GPU health monitoring (5-min checks)
      ├── nvidia_update_checker.py     # NVIDIA driver update monitoring (weekly)
      └── windows-desktop/ # Windows reboot monitoring with Discord notifications

/productivity/             # Task management and productivity tools
  ├── CONTEXT.md           # Technology overview, patterns, best practices
  ├── troubleshooting.md   # Error handling and debugging
  └── [Tools installed at ~/.claude/tools/task-manager/]

/media-servers/            # Media streaming services (Jellyfin, Plex)
  ├── CONTEXT.md           # Technology overview, GPU transcoding patterns
  └── jellyfin-ubuntu-manticore.md  # Jellyfin setup on ubuntu-manticore

/development/              # Programming language patterns and tools
  ├── python-CONTEXT.md    # Python development patterns
  ├── nodejs-CONTEXT.md    # Node.js development patterns
  └── bash-CONTEXT.md      # Shell scripting patterns

/legacy/                   # Backward compatibility during migration
  ├── patterns/            # Old patterns structure (temporary)
  ├── examples/            # Old examples structure (temporary)
  └── reference/           # Old reference structure (temporary)

Directory Usage Guidelines

  • Each technology directory is self-contained with its own context, troubleshooting, examples, and scripts
  • CONTEXT.md files provide technology overview, patterns, and best practices for Claude
  • troubleshooting.md files contain error handling and debugging information
  • /scripts/ subdirectories contain active operational code with their own CONTEXT.md
  • /examples/ subdirectories contain template configurations and reference implementations
  • /development/ contains general programming language patterns that apply across technologies
  • /legacy/ provides backward compatibility during the migration from the old structure

Documentation Maintenance Protocol

Automated Maintenance Triggers

Claude Code should automatically prompt for documentation updates when:

  1. New Technology Integration: When working with a technology that doesn't have a dedicated directory

    • Prompt: "I notice we're working with [technology] but don't have a dedicated /[technology]/ directory. Should I create the technology-first structure with CONTEXT.md and troubleshooting.md files?"

  2. New Error Patterns Discovered: When encountering and solving new issues

    • Prompt: "We just resolved a [technology] issue that isn't documented. Should I add this solution to [technology]/troubleshooting.md?"

  3. New Scripts or Operational Procedures: When creating new automation or workflows

    • Prompt: "I created new scripts/procedures for [technology]. Should I update [technology]/scripts/CONTEXT.md and add any new operational patterns?"

  4. Session End with Significant Changes: When completing complex tasks

    • Prompt: "We made significant changes to [technology] systems. Should I update our documentation to reflect the new patterns, configurations, or troubleshooting procedures we discovered?"

Documentation Update Checklist

When "update our documentation" is requested, systematically check:

Technology-Specific Updates:

  • Update [technology]/CONTEXT.md with new patterns or architectural changes
  • Add new troubleshooting scenarios to [technology]/troubleshooting.md
  • Update [technology]/scripts/CONTEXT.md for new operational procedures
  • Add working examples to [technology]/examples/ if new configurations were created

Cross-Technology Updates:

  • Update main CLAUDE.md loading rules if new keywords or triggers are needed
  • Add new technology directories to the Documentation Structure section
  • Update Directory Usage Guidelines if new organizational patterns emerge

Legacy Cleanup:

  • Check if any old patterns/examples/reference files can be migrated to technology directories
  • Update or remove outdated information that conflicts with new approaches

Self-Maintenance Features

Loading Rule Validation: Periodically verify that:

  • All technology directories have corresponding keyword triggers
  • Troubleshooting keywords include all common error scenarios
  • File paths in loading rules match actual directory structure

Documentation Completeness Check: Each technology directory should have:

  • CONTEXT.md (overview, patterns, best practices)
  • troubleshooting.md (error scenarios, emergency procedures)
  • examples/ (working configurations)
  • scripts/CONTEXT.md (if operational scripts exist)

Keyword Coverage Analysis: Ensure loading rules cover:

  • Technology names and common aliases
  • Error types and troubleshooting scenarios
  • Operational keywords (start, stop, configure, monitor)
  • Emergency keywords (shutdown, reset, recovery)

Warning Triggers

Claude Code should warn when:

  • Working extensively with a technology that lacks dedicated documentation structure
  • Solving problems that aren't covered in existing troubleshooting guides
  • Creating scripts or procedures without corresponding CONTEXT.md documentation
  • Encountering loading rules that reference non-existent files