Optimize CLAUDE.md and fix Gitea Actions Docker cache
CLAUDE.md optimization (329 → 104 lines): - Compress repetitive loading rules into keyword table - Remove 72 redundant "Note:" lines (info already in CONTEXT.md files) - State loading convention once instead of repeating 13 times - Preserve all functionality, special cases, and maintenance protocol - 68% reduction in size, easier to scan and maintain Gitea Actions Docker buildx fix: - Remove conditional from Docker Hub login step - Login now runs on all builds (PR and main), not just main - Fixes "push access denied" on second build when writing cache layers - Push flag still gates actual image publishing to main-only Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
3b2e031f45
commit
b237d6c056
383
CLAUDE.md
383
CLAUDE.md
@ -1,329 +1,104 @@
|
||||
# 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?"
|
||||
- Always have permission to run tests
|
||||
- Check imports when writing code (prevent NameErrors)
|
||||
- Temp files go in `.claude/tmp/`, clean up after
|
||||
- Prefer editing existing files over creating new ones
|
||||
- After complex tasks, prompt to save learnings to cognitive memory
|
||||
- At session end, ask: "Should I update our documentation?"
|
||||
- At 25% context remaining, ask: "Should I update docs before we lose context?"
|
||||
|
||||
## Automatic Context Loading Rules
|
||||
## Automatic Context Loading
|
||||
|
||||
### Technology-First Loading Rules
|
||||
When working with specific technologies, automatically load their dedicated context:
|
||||
### Loading Convention (applies to all technologies below)
|
||||
For each technology directory `{tech}/`:
|
||||
- Auto-load: `{tech}/CONTEXT.md` (overview, patterns, best practices)
|
||||
- Auto-load: `{tech}/troubleshooting.md` (errors, debugging, emergency procedures)
|
||||
- If in `{tech}/scripts/`: Also load `{tech}/scripts/CONTEXT.md`
|
||||
|
||||
**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
|
||||
### Keyword Triggers
|
||||
|
||||
**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)
|
||||
| Keywords | Tech Directory |
|
||||
|----------|----------------|
|
||||
| tdarr, transcode, ffmpeg, gpu transcoding, nvenc, scheduler | `tdarr/` |
|
||||
| docker, container, image, compose, kubernetes, k8s, dockerfile, podman | `docker/` |
|
||||
| virtual machine, vm, proxmox, kvm, hypervisor, guest, virtualization | `vm-management/` |
|
||||
| network, nginx, proxy, load balancer, dns, port, firewall, ssh, ssl, tls, npm, nginx proxy manager, reverse proxy, pihole, pi-hole, orbital sync | `networking/` |
|
||||
| monitoring, alert, notification, discord, health check, status, uptime, uptime kuma, status page, windows reboot, system monitor, gpu monitor, nvidia monitor | `monitoring/` |
|
||||
| task, todo, productivity, task manager, brain dump, focus, adhd, task tracking, context switch, task dashboard, n8n, workflow, automation, webhook, integration, ko-fi | `productivity/` |
|
||||
| openclaw, ai assistant, personal assistant, minimax, autonomous agent, agent skills | `productivity/openclaw/` |
|
||||
| jellyfin, plex, emby, media server, streaming, watchstate, watch history, nvidia driver, gpu transcoding | `media-servers/` |
|
||||
| media download, video download, yt-dlp, playwright, pokeflix, streaming scraper, web scraping, media archival | `media-tools/` |
|
||||
| gaming, steam, proton, steam tinker launch, stl, ready or not, gamescope, gamemode, dxvk, wine, windows games, linux gaming | `gaming/` |
|
||||
| server config, lxc config, docker compose deploy, infrastructure config, gitea, n8n config, foundry config, home assistant config, config sync | `server-configs/` |
|
||||
| database, sql, postgres, mysql, redis, mongodb, db optimization, query performance, database backup, connection pooling, schema migration | `databases/` |
|
||||
|
||||
**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)
|
||||
**Special cases:**
|
||||
- Pi-hole keywords → also load `networking/pihole-ha-setup.md`
|
||||
- n8n keywords → also load `productivity/n8n/CONTEXT.md`
|
||||
- Ko-fi keywords → also load `productivity/n8n/workflows/kofi-paper-dynasty.md`
|
||||
- Jellyfin keywords → also load `media-servers/jellyfin-ubuntu-manticore.md`
|
||||
|
||||
**Networking Keywords**
|
||||
- "network", "nginx", "proxy", "load balancer", "dns", "port", "firewall", "ssh", "ssl", "tls", "npm", "nginx proxy manager", "reverse proxy", "pihole", "pi-hole", "orbital sync", "dns ha", "high availability dns", "dns failover"
|
||||
- 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)
|
||||
- If "pihole" or "pi-hole" mentioned: Load `networking/pihole-ha-setup.md` (dual Pi-hole HA architecture)
|
||||
- Note: Comprehensive NPM configuration documented in `server-configs/networking/nginx-proxy-manager-pihole.md`
|
||||
- Note: Dual Pi-hole deployment: Primary (10.10.0.16), Secondary (10.10.0.226)
|
||||
- Note: Orbital Sync handles Pi-hole → Pi-hole synchronization (5-minute interval)
|
||||
- Note: NPM DNS sync script updates both Pi-holes hourly with proxy host entries
|
||||
### Directory Triggers
|
||||
- Working in `/tdarr/`, `/docker/`, etc. → auto-load that tech's CONTEXT.md + troubleshooting.md
|
||||
- Working in `/tdarr/scripts/`, etc. → auto-load parent CONTEXT.md + scripts/CONTEXT.md + troubleshooting.md
|
||||
|
||||
**Monitoring Keywords**
|
||||
- "monitoring", "alert", "notification", "discord", "health check", "status", "uptime", "uptime kuma", "uptime-kuma", "status page", "windows reboot", "system monitor", "gpu monitor", "nvidia monitor", "driver 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: Uptime Kuma on LXC 227 (10.10.0.227) - 20 active monitors with Discord alerts
|
||||
- Note: Status page at https://status.manticorum.com (internal: http://10.10.0.227:3001)
|
||||
- Note: Uptime Kuma API via `uptime-kuma-api` Python library, creds in `~/.claude/secrets/kuma_web_password`
|
||||
- Note: Windows desktop monitoring with Discord notifications available
|
||||
- Note: Comprehensive Tdarr API monitoring with dataclass-based status tracking
|
||||
- Note: Jellyfin GPU monitoring with auto-restart (`jellyfin_gpu_monitor.py`)
|
||||
- Note: NVIDIA driver update monitoring with weekly checks (`nvidia_update_checker.py`)
|
||||
|
||||
**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", "nvidia driver", "gpu transcoding", "nvenc"
|
||||
- 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
|
||||
- Note: NVIDIA driver packages held to prevent auto-updates; weekly update monitoring via Discord
|
||||
- Note: GPU health monitoring every 5 minutes with auto-restart capability
|
||||
|
||||
**Media Tools Keywords**
|
||||
- "media download", "video download", "yt-dlp", "playwright", "pokeflix", "streaming scraper", "web scraping", "media archival"
|
||||
- Load: `media-tools/CONTEXT.md` (technology overview and patterns)
|
||||
- Load: `media-tools/troubleshooting.md` (error handling and debugging)
|
||||
- If working in `/media-tools/scripts/`: Load `media-tools/scripts/CONTEXT.md` (script-specific documentation)
|
||||
- Note: Browser automation with Playwright for JavaScript-heavy streaming sites
|
||||
- Note: yt-dlp integration for video downloading
|
||||
- Note: Resumable downloads with JSON state persistence
|
||||
- Note: Anti-bot handling with realistic browser behaviors
|
||||
|
||||
**Gaming Keywords**
|
||||
- "gaming", "steam", "proton", "steam tinker launch", "stl", "ready or not", "gamescope", "gamemode", "dxvk", "wine", "windows games", "linux gaming"
|
||||
- Load: `gaming/CONTEXT.md` (technology overview and patterns)
|
||||
- Load: `gaming/troubleshooting.md` (error handling and debugging)
|
||||
- If working in `/gaming/scripts/`: Load `gaming/scripts/CONTEXT.md` (script-specific documentation)
|
||||
- Note: Steam Tinker Launch for advanced Proton configuration
|
||||
- Note: Ready or Not (Game ID: 1144200) specific configs available
|
||||
- Note: NVIDIA GPU optimizations with NVAPI, DXVK, GameScope
|
||||
- Note: Config location: ~/.config/steamtinkerlaunch/
|
||||
- Note: 12 gaming scripts for RON setup, STL logs, Proton testing
|
||||
|
||||
**Server Configs Keywords**
|
||||
- "server config", "lxc config", "docker compose deploy", "infrastructure config", "gitea", "n8n config", "foundry config", "home assistant config", "config sync"
|
||||
- Load: `server-configs/README.md` (technology overview)
|
||||
- Note: Version-controlled infrastructure configurations for all hosts
|
||||
- Note: Centralized Docker Compose and VM/LXC configuration management
|
||||
- Note: sync-configs.sh for automated config deployment and synchronization
|
||||
- Note: Covers Proxmox LXCs, VMs, and physical servers (ubuntu-manticore)
|
||||
- Note: Services include: Gitea, n8n, Home Assistant, Foundry VTT, OpenClaw, Uptime Kuma, Discord bots, databases
|
||||
|
||||
**Databases Keywords**
|
||||
- "database", "sql", "postgres", "mysql", "redis", "mongodb", "db optimization", "query performance", "database backup", "connection pooling", "schema migration"
|
||||
- Load: `databases/CONTEXT.md` (technology overview and patterns)
|
||||
- Load: `databases/troubleshooting.md` (error handling and debugging)
|
||||
- Note: Database design patterns (normalization, indexing, schema versioning)
|
||||
- Note: Performance optimization (connection pooling, query optimization, caching)
|
||||
- Note: Backup and recovery strategies (point-in-time recovery, replication)
|
||||
- Note: Security and access control (privilege management, encryption, audit logging)
|
||||
|
||||
### 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
|
||||
### Troubleshooting Triggers
|
||||
Keywords: shutdown, stop, emergency, reset, recovery, crash, broken, not working, error, issue, problem, debug, troubleshoot, fix
|
||||
- Detect tech from context → load BOTH CONTEXT.md AND troubleshooting.md
|
||||
|
||||
### File Extension Triggers
|
||||
For programming languages, load general development context:
|
||||
- `.py` → `development/python-CONTEXT.md`
|
||||
- `.js`, `.mjs`, `.ts` → `development/nodejs-CONTEXT.md`
|
||||
- `.sh`, `.bash`, `.zsh` → `development/bash-CONTEXT.md`
|
||||
|
||||
**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
|
||||
### Loading Priority
|
||||
1. File extension triggers (highest)
|
||||
2. Directory context
|
||||
3. Keyword triggers (additive)
|
||||
4. Load 3-4 files max per trigger
|
||||
|
||||
## 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
|
||||
/{technology}/ # Each tech is self-contained
|
||||
├── CONTEXT.md # Overview, patterns, best practices
|
||||
├── troubleshooting.md # Errors, debugging, emergency recovery
|
||||
├── examples/ # Working configs and templates
|
||||
└── scripts/
|
||||
├── CONTEXT.md # Script-specific docs
|
||||
└── *.py, *.sh # Active operational scripts (production code)
|
||||
|
||||
/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
|
||||
├── jellyfin_gpu_monitor.py # Jellyfin GPU health monitoring (5-min checks)
|
||||
├── nvidia_update_checker.py # NVIDIA driver update monitoring (weekly)
|
||||
└── 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)
|
||||
/development/ # Cross-tech language patterns
|
||||
├── python-CONTEXT.md
|
||||
├── nodejs-CONTEXT.md
|
||||
└── bash-CONTEXT.md
|
||||
```
|
||||
|
||||
### Directory Usage Guidelines
|
||||
Technologies: tdarr, docker, vm-management, networking, monitoring, productivity, productivity/openclaw, productivity/n8n, media-servers, media-tools, gaming, server-configs, databases
|
||||
|
||||
- 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
|
||||
|
||||
## Documentation Maintenance Protocol
|
||||
### Auto-prompt when:
|
||||
1. **New tech** without dedicated directory → "Should I create `/{tech}/` structure?"
|
||||
2. **New error solved** → "Should I add to `{tech}/troubleshooting.md`?"
|
||||
3. **New scripts created** → "Should I update `{tech}/scripts/CONTEXT.md`?"
|
||||
4. **Session end with changes** → "Should I update documentation?"
|
||||
|
||||
### Automated Maintenance Triggers
|
||||
Claude Code should automatically prompt for documentation updates when:
|
||||
### Update checklist:
|
||||
- `{tech}/CONTEXT.md` for new patterns/architecture
|
||||
- `{tech}/troubleshooting.md` for new errors/solutions
|
||||
- `{tech}/scripts/CONTEXT.md` for new procedures
|
||||
- Main CLAUDE.md if new keywords/triggers needed
|
||||
|
||||
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?"
|
||||
### Validation (periodic):
|
||||
- All tech dirs have keyword triggers
|
||||
- Loading paths match actual files
|
||||
- Each tech has CONTEXT.md + troubleshooting.md
|
||||
|
||||
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
|
||||
### Warning triggers:
|
||||
- Working with tech lacking docs structure
|
||||
- Solving problems not in troubleshooting guides
|
||||
- Creating scripts without CONTEXT.md
|
||||
- Loading rules reference missing files
|
||||
|
||||
@ -143,7 +143,6 @@ jobs:
|
||||
# 3. Copy token to Gitea repo → Settings → Secrets → Actions
|
||||
#
|
||||
- name: Login to Docker Hub
|
||||
if: github.ref == 'refs/heads/main'
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
@ -198,8 +197,8 @@ jobs:
|
||||
yourusername/yourrepo:latest
|
||||
yourusername/yourrepo:v${{ steps.meta.outputs.version }}
|
||||
yourusername/yourrepo:${{ steps.meta.outputs.version_sha }}
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
cache-from: type=registry,ref=yourusername/yourrepo:buildcache
|
||||
cache-to: type=registry,ref=yourusername/yourrepo:buildcache,mode=max
|
||||
|
||||
# ==============================================
|
||||
# 7. BUILD SUMMARY
|
||||
@ -438,8 +437,9 @@ jobs:
|
||||
# - Look for HTTP error codes in Actions logs
|
||||
#
|
||||
# 5. Build cache not working
|
||||
# - GitHub Actions cache is stored per repository
|
||||
# - Cache is shared across branches
|
||||
# - May need to clear cache if corrupted
|
||||
# - Uses registry-based caching (pushes cache layers to Docker Hub)
|
||||
# - Requires Docker Hub login to read/write cache
|
||||
# - Cache tag is "yourusername/yourrepo:buildcache"
|
||||
# - To clear cache: delete the buildcache tag on Docker Hub
|
||||
#
|
||||
# ==============================================
|
||||
|
||||
Loading…
Reference in New Issue
Block a user