claude-home/CLAUDE.md

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"
  • 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)
  • Note: Comprehensive NPM configuration documented in networking/npm-configuration.md

Monitoring Keywords

• "monitoring", "alert", "notification", "discord", "health check", "status", "uptime", "windows reboot", "system 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: Windows desktop monitoring with Discord notifications available
  • Note: Comprehensive Tdarr API monitoring with dataclass-based status tracking

Directory Context Triggers

When working in specific directories:

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

• 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

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
      └── windows-desktop/ # Windows reboot monitoring with Discord notifications

/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