# Documentation

## Overview

This directory contains all technical documentation for the Castaldi Family Homelab infrastructure.

---

## Quick Reference

### 📘 Runbooks & Guides

- **[TECHNICAL_RUNBOOK.md](TECHNICAL_RUNBOOK.md)** - Complete infrastructure reference, emergency procedures, and maintenance schedule
- **[SECURITY_AUDIT_REPORT.md](SECURITY_AUDIT_REPORT.md)** - 🔴 Security audit findings, exposed credentials, and remediation steps

---

## Knowledge Base Articles (KBAs/)

Structured troubleshooting articles following the incident → resolution format.

### GitOps & Deployment

- **[KBA-001: Komodo GitOps Stack Deployment Failures](KBAs/KBA-001-Komodo-GitOps-Stack-Deployment-Failures.md)**  
  Troubleshooting guide for Git-linked stack pull/deploy failures, canonicalize errors, and Docker image tag issues.

---

## Standard Operating Procedures (SOPs/)

Step-by-step guides for operational tasks and migrations.

### Infrastructure Deployment

- **[SOP-002: Initial Infrastructure Deployment](SOPs/SOP-002-Initial-Infrastructure-Deployment.md)**  
  Complete guide for deploying the homelab from scratch, including secure repository setup, Ansible control node configuration, core service deployment, and GitOps integration.

### Stack Management

- **[SOP-001: Migrate Stack from UI to Git](SOPs/SOP-001-Migrate-Stack-from-UI-to-Git.md)**  
  Complete guide for converting Komodo stacks from UI-defined to Git-based deployment, including secrets management and verification steps.

---

## Document Conventions

- **KBA-XXX:** Troubleshooting articles with clear problem/solution format (stored in `KBAs/`)
- **SOP-XXX:** Procedural guides for operational tasks (stored in `SOPs/`)
- **Runbooks:** Infrastructure reference and emergency procedures (root level)

---

## Contributing

When documenting new issues or procedures:

1. **KBAs:** Create in `KBAs/` folder for troubleshooting scenarios with clear diagnosis → resolution
2. **SOPs:** Create in `SOPs/` folder for repeatable operational procedures and migrations
3. **Update Runbook:** Add new emergency procedures to TECHNICAL_RUNBOOK.md
4. **Update Repository Memory:** Store critical lessons in `/memories/repo/`
5. **Commit Messages:** Use conventional commits (e.g., `docs(kba): add KBA-002 for...`)

---

**Last Updated:** April 12, 2026