782067344a
- Add productivity keywords (task, n8n, workflow, ko-fi integration) - Add media server keywords (jellyfin, plex, watchstate) - Update directory context triggers for new technology folders - Add troubleshooting context loading for productivity 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
271 lines
16 KiB
Markdown
271 lines
16 KiB
Markdown
# 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)
|
|
|
|
**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
|