From 27733e99f975f627c2799e20e54c583464380b55 Mon Sep 17 00:00:00 2001
From: wheelz <claytonwheeler3113@gmail.com>
Date: Thu, 28 May 2026 19:02:03 +0000
Subject: [PATCH] chore: add Claude Code project context

---
 .claude/commands/validate-compose.md   | 11 ++++++++
 .claude/skills/docker-compose-stack.md | 29 +++++++++++++++++++++
 CLAUDE.md                              | 35 ++++++++++++++++++++++++++
 3 files changed, 75 insertions(+)
 create mode 100644 .claude/commands/validate-compose.md
 create mode 100644 .claude/skills/docker-compose-stack.md
 create mode 100644 CLAUDE.md

diff --git a/.claude/commands/validate-compose.md b/.claude/commands/validate-compose.md
new file mode 100644
index 0000000..2a445df
--- /dev/null
+++ b/.claude/commands/validate-compose.md
@@ -0,0 +1,11 @@
+# Validate Docker Compose Stack
+
+Validate the Compose stack named in `$ARGUMENTS`.
+
+If `$ARGUMENTS` is empty, inspect the repository and validate all `*-compose.yml` files you can safely validate.
+
+Steps:
+1. Identify the compose file and matching `.env.example` file.
+2. Run `docker compose config` with the example env file when possible.
+3. Report syntax errors, missing variables, unsupported options, and manual values required.
+4. Do not modify files unless the user asks.
diff --git a/.claude/skills/docker-compose-stack.md b/.claude/skills/docker-compose-stack.md
new file mode 100644
index 0000000..5c7a722
--- /dev/null
+++ b/.claude/skills/docker-compose-stack.md
@@ -0,0 +1,29 @@
+# Docker Compose Stack Skill
+
+Use this skill when adding, reviewing, or modifying regular Docker Compose stacks in this repository.
+
+## Workflow
+
+1. Confirm the service belongs in the non-Swarm Compose repo.
+2. Create or update `<service>-compose.yml`.
+3. Create or update `<service>.env.example` with placeholders only.
+4. Keep real secrets out of the repo.
+5. Include healthchecks when practical.
+6. Use configurable paths and document required host directories.
+7. Validate with `docker compose config` when Docker is available.
+8. Summarize changed files and any manual setup steps.
+
+## Compose Standards
+
+- Use 2-space YAML indentation.
+- Prefer explicit image tags over unpinned `latest` when stability matters.
+- Use `restart: unless-stopped` for ordinary long-running services unless there is a reason not to.
+- Put service-specific networks at the bottom of the file.
+- Avoid hardcoding passwords, domains, tokens, or private IP assumptions unless they are already public repo conventions.
+- For reverse proxy routing, add comments instead of assuming a specific proxy unless the user provides details.
+
+## Validation Command Pattern
+
+```bash
+docker compose --env-file <service>.env.example -f <service>-compose.yml config
+```
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a927501
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,35 @@
+# Docker Compose Stacks Repository
+
+This repository is for regular, non-Swarm Docker Compose stacks for Wheelz's HomeLab.
+
+## Repository Purpose
+
+- Store standalone Docker Compose stacks that run with `docker compose`.
+- Do not add Docker Swarm stack files here.
+- Use this repo for services that are deployed on a single Docker host or non-Swarm compose environment.
+
+## Rules
+
+- Never commit real secrets, passwords, tokens, API keys, private keys, or recovery codes.
+- Use `.env.example` files for required variables.
+- Prefer clear service-specific filenames such as `<service>-compose.yml` and `<service>.env.example`.
+- Keep persistent data paths explicit and documented.
+- Prefer named volumes or clearly documented bind mounts. If bind mounts are used, make host paths configurable through `.env` variables.
+- Add comments for non-obvious ports, volumes, healthchecks, hardware acceleration, and reverse-proxy expectations.
+- Preserve existing files unless the user explicitly asks to replace or reorganize them.
+- Do not push to Gitea unless the user explicitly asks.
+
+## Validation
+
+For regular Compose files, validate with:
+
+```bash
+docker compose --env-file <service>.env.example -f <service>-compose.yml config
+```
+
+If the example env intentionally contains placeholder values that prevent validation, explain what placeholders must be filled in.
+
+## Current Files
+
+- `immich-compose.yml` — regular Docker Compose stack for Immich.
+- `immich.env.example` — example environment variables for Immich.