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

**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"
  - 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

### 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
      └── 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