From 889a666c810af9f48f4ee6adf2d4d4cf3e0ab63d Mon Sep 17 00:00:00 2001
From: Stephen Klein <skier@mini.canadabot.net>
Date: Wed, 10 Jun 2026 21:41:00 -0400
Subject: [PATCH] Add CLAUDE.md with static project context

Covers pipeline architecture, file map, key decisions, coding conventions,
and how to syntax-check. Points to TODO.md, CHANGELOG.md, and SERVICES.md
for dynamic information. Also removes CLAUDE.md from .gitignore.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore |  3 --
 CLAUDE.md  | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+), 3 deletions(-)
 create mode 100644 CLAUDE.md

diff --git a/.gitignore b/.gitignore
index cbb6294..4bff0f0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,5 @@
 # HOPS .gitignore
 
-# Claude Code development documentation
-CLAUDE.md
-
 # Log files
 *.log
 
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d62854d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,84 @@
+# HOPS - Claude Code Project Guide
+
+## Project Overview
+
+HOPS (Homelab Orchestration Provisioning Script) is a bash-based tool that
+deploys homelab infrastructure via Docker Compose. It presents an interactive
+menu for selecting services, generates a docker-compose.yml and .env, installs
+Docker if needed, and manages the lifecycle of the deployment.
+
+**Target platform**: Linux only (Ubuntu 20.04+, Debian 11+, Linux Mint 20+).
+macOS and WSL2 are on the future roadmap, not in scope for 1.0.0.
+
+## Install Pipeline (Path A -- canonical)
+
+```
+sudo ./hops          # Entry point and management menu
+  -> install         # Full installation logic (sourced by hops)
+    -> services      # Service definitions and compose generators (sourced by install)
+  -> uninstall       # Removal logic (standalone)
+```
+
+All other top-level scripts and `lib/privileges.sh` were Path B artifacts and
+have been deleted. Do not recreate them.
+
+## File Map
+
+| File | Purpose |
+|------|---------|
+| `hops` | Entry point, management menu, update logic |
+| `install` | Full install flow: Docker setup, service selection, compose generation, firewall |
+| `uninstall` | Reversal of install: stops containers, removes dirs, optionally purges Docker |
+| `services` | Single canonical service catalog: compose generators, port map, image refs |
+| `lib/common.sh` | Logging, UI helpers, shared utilities -- source this, don't duplicate |
+| `lib/system.sh` | OS detection, Docker install, system requirement checks |
+| `lib/docker.sh` | Docker service management, status checks, network helpers |
+| `lib/security.sh` | Password generation, validation, firewall, security audit |
+| `lib/validation.sh` | Input sanitisation and validation functions |
+| `lib/secrets.sh` | .env encryption at rest (being fixed and wired in -- see TODO M4/A4/S1) |
+
+## Key Architectural Decisions
+
+- **One service catalog**: `services` is the single source of truth for images,
+  ports, and compose definitions. `lib/docker.sh` has a secondary map that must
+  be kept in sync until reconciled (TODO A2).
+- **Latest image tags**: all service images use `latest`, not pinned versions.
+- **Secrets**: `lib/secrets.sh` will encrypt the `.env` file at rest using gpg.
+  Currently being fixed -- the old AES-GCM implementation was broken.
+- **No duplicate functions**: consolidate into `lib/common.sh`. Do not define
+  `log`, `error_exit`, `warning`, `success`, or `info` in any other file.
+
+## Coding Conventions
+
+- Bash only. No Python, no Node, no external interpreters required at runtime.
+- ASCII only -- no Unicode, no emojis in scripts or output strings.
+- No comments explaining what the code does. Only add a comment when the WHY
+  is non-obvious (hidden constraint, workaround, subtle invariant).
+- Error handling: use `set -e` with care. Arithmetic increments must use
+  `x=$((x + 1))` not `((x++))` -- the latter aborts under `set -e` when the
+  pre-increment value is 0.
+- Temp files: always use `mktemp`, never `/tmp/name_$$`.
+- User home resolution: use `getent passwd "$SUDO_USER" | cut -d: -f6`,
+  never `eval echo "~$SUDO_USER"`.
+- Command arrays: build commands as bash arrays, not strings, to avoid
+  word-splitting on unusual usernames or paths.
+
+## Running / Testing
+
+There is no test suite. Validate with:
+
+```bash
+bash -n hops install uninstall services   # syntax check
+bash -n lib/*.sh
+```
+
+Full integration testing requires a Linux VM. The scripts must be run as root
+or via sudo on a supported distro.
+
+## Dynamic Information
+
+The following docs change frequently -- check them rather than this file:
+
+- **TODO.md** -- prioritised bug list, cleanup tasks, and feature backlog
+- **CHANGELOG.md** -- version history and unreleased changes
+- **SERVICES.md** -- supported service list with ports and upstream links