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/)**
- Load: `patterns/` (relevant to script type)
- Load: `reference/` (relevant troubleshooting guides)
- 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"
  - Load: `reference/docker/tdarr-troubleshooting.md`
  - Load: `patterns/docker/distributed-transcoding.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
- 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
```

Each pattern file should reference relevant examples and reference materials.

### Directory Usage Guidelines

- `/scripts/` - Contains actively used scripts for home lab management and operations
- `/examples/` - Contains example configurations and template scripts for reference
- `/patterns/` - Best practices and architectural guidance  
- `/reference/` - Troubleshooting guides and technical references