truenas/CLAUDE.md

---
version: 1.0.0
last_updated: 2025-12-16
infrastructure_source: CLAUDE_STATUS.md
repository_type: TrueNas

TrueNas_version: 
vm_count: 
template_count: 
lxc_count: 
working_directory: /home/jramos/homelab
git_remote: http://192.168.2.102:3060/jramos/truenas.git
---

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

**Live Status** | See `CLAUDE_STATUS.md` for current inventory |

**Key Services:**


## Agent Selection Guide

When working with this repository, choose the appropriate agent based on task type:

## Agent Selection Guide

**CRITICAL RULE**: The Main Agent is a **ROUTER ONLY**. It must NEVER write code, documentation, or config files directly. It must ALWAYS delegate to a sub-agent.

| Task Type | Primary Agent | Tools Available | Notes |
|-----------|---------------|-----------------|-------|
| **Git Operations** | `librarian` | Bash, Read, Grep, Edit, Write | Commits, branches, merges, .gitignore |
| **Documentation** | `scribe` | Read, Grep, Glob, Edit, Write | READMEs, architecture docs, diagrams |
| **Infrastructure Ops** | `lab-operator` | Bash, Read, Grep, Glob, Edit, Write | TrueNas, Docker, networking, storage |
| **Code/IaC/Scripting** | `backend-builder` | Bash, Read, Grep, Glob, Edit, Write | Ansible, Terraform, Python, **Shell Scripts** |
| **Orchestration** | Main Agent | All tools | **ONLY** for routing and high-level planning. |

### Task Routing Decision Tree

```
START
│
├── Am I (Main Agent) about to write a file or run a command?
│   └── YES → **STOP**. Identify the correct sub-agent below.
│
├── Is this a git/version control task?
│   └── Yes → Use `librarian`
│
├── Is this documentation (README, guides, diagrams)?
│   └── Yes → Use `scribe`
│
├── Does this require system commands (docker, ssh, proxmox) or execution?
│   └── Yes → Use `lab-operator`
│
├── Is this code, script, or config creation (Ansible, Python, Bash, Terraform)?
│   └── Yes → Use `backend-builder`
│
└── Is this a purely conversational/planning question?
    └── Yes → Main Agent answers directly.
```

### Agent Collaboration Patterns

**Documentation Workflow:**
1. `backend-builder` or `lab-operator` creates/modifies infrastructure
2. `scribe` updates documentation
3. `librarian` commits all changes

**Infrastructure Deployment:**
1. `backend-builder` writes IaC (Ansible/Terraform/Compose)
2. `lab-operator` deploys to TrueNas/Docker
3. `scribe` documents deployment
4. `librarian` commits configuration

## Infrastructure Overview

**For detailed, current infrastructure inventory, see:**
- **Live Status**: `CLAUDE_STATUS.md` (most current)
- **Service Details**: 
- **Complete Index**: 

**Quick Summary:**
- **VMs**: 
- **APPS**: 
- **Containers**:
- **Storage Pools**:
- **Monitoring**: VM 101 at 192.168.2.114 (Grafana/Prometheus/PVE Exporter)

**Note**: Infrastructure details change frequently. Always reference `CLAUDE_STATUS.md` for accurate counts, IPs, and status.

## Main Agent Operational Rules (STRICT)

1.  **NO DIRECT WRITING**: The Main Agent must **NEVER** use the `Write` or `Edit` tools to create content in the repository.
    * If you need to write a script $\to$ Call `backend-builder`.
    * If you need to write docs $\to$ Call `scribe`.
    * If you need to commit $\to$ Call `librarian`.

2.  **NO DIRECT EXECUTION**: The Main Agent must **NEVER** use `Bash` to execute system commands.
    * If you need to run a command $\to$ Call `lab-operator`.

3.  **ROUTING FIRST**: Your primary goal is to identify the intent and immediately invoke the correct sub-agent. Do not "draft" the solution first.

## Working with This Environment

### Universal Workflow
For every complex task, every Agent must follow this loop:
1.  **Read**: `cat CLAUDE_STATUS.md` to see where we are.
2.  **Execute**: Perform your specific task (Coding, Docs, Sysadmin).
3.  **Update**: Edit `CLAUDE_STATUS.md` to mark your step as `[x]` and update the "Current Context".

### Status File Template
If `CLAUDE_STATUS.md` is missing or corrupted, recover it from the latest disaster recovery export:
- **Location**: `disaster-recovery/homelab-export-YYYYMMDD-HHMMSS/CLAUDE_STATUS.md`
- **Alternative**: Use the scribe agent to recreate from current infrastructure state

**Minimum required structure:**
```markdown
# TrueNas Infrastructure Status
**Last Updated**: YYYY-MM-DD HH:MM:SS
**Export Reference**: disaster-recovery/homelab-export-YYYYMMDD-HHMMSS

## Current Infrastructure Snapshot
- TrueNas Scale (192.168.2.150)


## Current Initiative
**Goal**: [Initiative description]
**Phase**: [Planning / Implementation / Testing]
**Progress Checklist**: [Task list with checkboxes]

## Recent Infrastructure Changes

### Access Patterns

- **TrueNas Web UI**: Primary management interface for VM/CT/NAS lifecycle operations
- **Gitea**: CI/CD pipelines for infrastructure testing and deployment

### Maintenance Considerations

- **Uptime**: Track uptime metrics in disaster recovery exports for trend analysis
- **Storage Growth**: PBS-Backups at 27.43%,(see CLAUDE_STATUS.md for current metrics)
- **Capacity Planning**: 

## Development Setup

The repository structure will house:
- Ansible playbooks and roles for infrastructure automation
- Terraform/OpenTofu configurations for TrueNas resource provisioning
- Docker Compose files for service definitions
- Documentation and runbooks for common operations
- Network diagrams and architecture documentation

## Notes

- This is a Windows Subsystem for Linux (WSL2) environment
- Working directory: /home/jramos/truenas