Imported from tonur/homelab (AGENTS.md). Install upstream with npx skills add tonur/homelab. Copyright stays with the author.

Homelab Agent Guidelines

When you need to search docs, use context7 tools. If you are unsure how to do something, use gh_grep tools to search code examples from GitHub.

Agent Restrictions

⚠️ IMPORTANT: Agents cannot commit git changes unless explicitly granted permission by the user. ASK EACH TIME YOU WANT TO COMMIT CHANGES.

PLEASE also understand that this project is GitOps, which means that any changes will need to be pushed to Git and reconciled (potentially automatically) by Flux CD.

DO NOT apply kubectl files directly without asking for permission. You can use kubectl and delete stuff if you have permission, but most changes should go through Git and Flux for consistency and traceability.

Documentation Policy

• No docs/ folder: All documentation deleted
• Only README.md and AGENT.md: These are the sole documentation files
• Self-documenting code: Code should be clear and comments only where necessary

Helm Chart Guidelines

• No complex templating: Keep charts as simple as possible
• No Helm best practices needed: These charts are only used by you, not shared
• Avoid unnecessary abstractions: Don't use helper templates, values files, or complex conditionals
• Direct is better: Use static manifests with simple substitutions where needed
• Focus on working, not elegant: Deployments that work are more important than perfectly templated charts
• Versioning: Use version: 0.0.0-local for all charts to avoid confusion with actual versioning - it will update automatically when you commit changes

Other notes

• Cloud registry with proxy: Use Ollama Cloud or similar services for application deployments
• External Secrets v1: Always use apiVersion: external-secrets.io/v1 for ExternalSecret manifests
• App chart structure: Each app has its own chart in charts/<app>/ with individual manifest files (deployment.yaml, service.yaml, ingress.yaml, pvc.yaml, externalsecret.yaml) without app name prefixes
• HelmReleases: Add HelmRelease to charts/homelab-apps/templates/<app>.yaml referencing ./charts/<app>
• Bitwarden/ExternalSecrets: Always use the secret store of "bitwarden-secrets-manager" to get secrets

Project Overview

This is a GitOps-managed homelab running k3s. The infrastructure uses Flux CD for continuous deployment from Git - not via Kustomization, everything is via HelmReleases.

Key Components

• Kubernetes: k3s cluster (single node: Gigabyte)
• GitOps: Flux CD manages all deployments from Git repository
• Networking: Traefik ingress with native load balancing
• Secrets: External Secrets Operator + Bitwarden integration
• Provisioning: Ansible automation with SOPS-encrypted secrets
• Domain: kragh.dev with automated TLS via cert-manager

Critical Workflow Notes

• All infrastructure changes go through Git → Flux
• Never commit secrets to Git (use Bitwarden + External Secrets)
• Respect dependency order: cert-manager → config → external-secrets → secrets-config → ingress → apps
• Flux timeout: Always use prefix timeout 10 for flux commands to avoid hanging indefinitely

Project Structure

homelab/
├── ansible/          # Infrastructure provisioning (Ansible)
├── charts/           # Helm charts for applications
├── README.md         # Main project documentation
├── AGENT.md          # Agent guidelines and project context
└── scripts/          # Utility scripts