blumeops/docs/explanation/explanation.md

---
title: Explanation
tags:
  - explanation
---

# Explanation

Understanding-oriented content explaining the "why" behind BlumeOps design decisions.

## Philosophy

| Article | Description |
|---------|-------------|
| [[why-gitops]] | Why infrastructure-as-code and GitOps for a homelab |

## Design

| Article | Description |
|---------|-------------|
| [[architecture]] | How all the pieces fit together |
| [[security-model]] | Network security, secrets, and access control |
Add Phase 5: explanation documentation (#96) ## Summary - Create `docs/explanation/` directory with index and three explanation articles - why-gitops: Philosophy of GitOps for homelabs (memory, rollback, AI context) - architecture: How pieces fit together (ASCII diagrams of hosts, data flow, secrets) - security-model: Tailscale zero-trust, 1Password secrets, access control philosophy - Update docs/index.md with How-to and Explanation section links - Update exploring-the-docs to link Explanation section Decision log deferred to future work. ## Deployment and Testing - [x] Pre-commit hooks pass (including doc-links validator) - [ ] Build and deploy to docs.ops.eblu.me to verify rendering 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/96 2026-02-03 20:33:39 -08:00			`---`
Update all docs titles to human-readable (#117) ## Summary - Updated frontmatter `title:` in all 63 doc cards from slug-case to human-readable (e.g. `borgmatic` → `Borgmatic`, `ai-assistance-guide` → `AI Assistance Guide`) - Titles now closely match file stems so `[[wiki-links]]` render naturally without alternate anchor text - Corrected titles that diverged from stems (e.g. `host-inventory` → `Hosts`, `grafana-alloy` → `Alloy`, `argocd-applications` → `Apps`) - Deleted `title-test-alpha.md` and `title-test-beta.md` test cards and removed their reference index entry ## Deployment and Testing - [x] `docs-check-links` passes — all wiki-links valid - [x] `docs-check-index` passes - [x] `docs-check-filenames` passes - [ ] Verify titles render correctly on docs site after deploy Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/117 2026-02-07 21:44:57 -08:00			`title: Explanation`
Add Phase 5: explanation documentation (#96) ## Summary - Create `docs/explanation/` directory with index and three explanation articles - why-gitops: Philosophy of GitOps for homelabs (memory, rollback, AI context) - architecture: How pieces fit together (ASCII diagrams of hosts, data flow, secrets) - security-model: Tailscale zero-trust, 1Password secrets, access control philosophy - Update docs/index.md with How-to and Explanation section links - Update exploring-the-docs to link Explanation section Decision log deferred to future work. ## Deployment and Testing - [x] Pre-commit hooks pass (including doc-links validator) - [ ] Build and deploy to docs.ops.eblu.me to verify rendering 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/96 2026-02-03 20:33:39 -08:00			`tags:`
			`- explanation`
			`---`

			`# Explanation`

			`Understanding-oriented content explaining the "why" behind BlumeOps design decisions.`

			`## Philosophy`

			`\| Article \| Description \|`
			`\|---------\|-------------\|`
			`\| [[why-gitops]] \| Why infrastructure-as-code and GitOps for a homelab \|`

			`## Design`

			`\| Article \| Description \|`
			`\|---------\|-------------\|`
			`\| [[architecture]] \| How all the pieces fit together \|`
			`\| [[security-model]] \| Network security, secrets, and access control \|`