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.

Automatic Context Loading Rules

File Extension Triggers

When working with files, automatically load relevant documentation:

Python (.py, .pyx, .pyi)

• Load: patterns/python/
• Load: reference/python/
• If Django/Flask detected: Load examples/python/web-frameworks.md
• If requests/httpx detected: Load examples/python/api-clients.md

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

• Load: patterns/nodejs/
• Load: reference/nodejs/
• If package.json exists: Load examples/nodejs/package-management.md

Vue.js (.vue, vite.config., nuxt.config.)

• Load: patterns/vuejs/
• Load: reference/vuejs/
• Load: examples/vuejs/component-patterns.md

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

• Load: patterns/bash/
• Load: reference/bash/
• If systemd mentioned: Load examples/bash/service-management.md

Docker (Dockerfile, docker-compose.yml, .dockerignore)

• Load: patterns/docker/
• Load: reference/docker/
• Load: examples/docker/multi-stage-builds.md

Directory Context Triggers

When working in specific directories:

Docker-related directories (/docker/, /containers/, /compose/)

• Load: patterns/docker/
• Load: examples/docker/
• Load: reference/docker/troubleshooting.md

Database directories (/db/, /database/, /mysql/, /postgres/, /mongo/)

• Load: patterns/databases/
• Load: examples/databases/
• Load: reference/databases/

Network directories (/network/, /networking/, /nginx/, /traefik/)

• Load: patterns/networking/
• Load: examples/networking/
• Load: reference/networking/troubleshooting.md

VM directories (/vm/, /virtual/, /proxmox/, /kvm/)

• Load: patterns/vm-management/
• Load: examples/vm-management/
• Load: reference/vm-management/

Scripts directory (/scripts/, /scripts/*/)

• Load: patterns/ (relevant to script type)
• Load: reference/ (relevant troubleshooting guides)
• Load: scripts/*/README.md (subsystem-specific documentation)
• Context: Active operational scripts - treat as production code

Keyword Triggers

When user mentions specific terms, automatically load relevant docs:

Troubleshooting Keywords

• "debug", "error", "fail", "broken", "not working", "issue"
  • Load: reference/{relevant-tech}/troubleshooting.md
  • Load: examples/{relevant-tech}/debugging.md

Configuration Keywords

• "config", "configure", "setup", "install", "deploy"
  • Load: patterns/{relevant-tech}/
  • Load: examples/{relevant-tech}/configuration.md

Performance Keywords

• "slow", "performance", "optimize", "memory", "cpu"
  • Load: reference/{relevant-tech}/performance.md
  • Load: examples/{relevant-tech}/optimization.md

Security Keywords

• "secure", "ssl", "tls", "certificate", "auth", "firewall"
  • Load: patterns/networking/security.md
  • Load: reference/networking/security.md

Database Keywords

• "database", "db", "sql", "mysql", "postgres", "mongo", "redis"
  • Load: patterns/databases/
  • Load: examples/databases/

Container Keywords

• "docker", "container", "image", "compose", "kubernetes", "k8s"
  • Load: patterns/docker/
  • Load: examples/docker/

Network Keywords

• "network", "nginx", "proxy", "load balancer", "dns", "port", "firewall"
  • Load: patterns/networking/
  • Load: examples/networking/

SSH Keywords

• "ssh", "key", "authentication", "authorized_keys", "ssh-copy-id"
  • Load: patterns/networking/ssh-key-management.md
  • Load: examples/networking/ssh-homelab-setup.md
  • Load: reference/networking/ssh-troubleshooting.md

VM Keywords

• "virtual machine", "vm", "proxmox", "kvm", "hypervisor", "guest"
  • Load: patterns/vm-management/
  • Load: examples/vm-management/

Tdarr Keywords

• "tdarr", "transcode", "ffmpeg", "gpu transcoding", "nvenc", "forEach error", "gaming detection", "scheduler"
  • Load: reference/docker/tdarr-troubleshooting.md
  • Load: patterns/docker/distributed-transcoding.md
  • Load: scripts/tdarr/README.md (for automation and scheduling)
  • Note: Gaming-aware scheduling system with configurable time windows available

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

• Load pattern files first for overview
• Load relevant examples for implementation details
• Load reference files for troubleshooting and edge cases
• Maximum of 3 documentation files per trigger to maintain efficiency
• If context becomes too large, prioritize most recent/specific files

Documentation Structure

/patterns/          # Technology overviews and best practices
/examples/          # Complete working implementations  
/reference/         # Troubleshooting, cheat sheets, fallback info
/scripts/           # Active scripts and utilities for home lab operations
  ├── tdarr/        # Tdarr automation with gaming-aware scheduling
  └── <future>/     # Other organized automation subsystems

Each pattern file should reference relevant examples and reference materials.

Directory Usage Guidelines

• /scripts/ - Contains actively used scripts for home lab management and operations
  • Organized by subsystem (e.g., tdarr/, networking/, vm-management/)
  • Each subsystem includes its own README.md with complete documentation
• /examples/ - Contains example configurations and template scripts for reference
• /patterns/ - Best practices and architectural guidance
• /reference/ - Troubleshooting guides and technical references