chore: add Claude Code project context

.claude/commands/validate-swarm.md

@@ -0,0 +1,12 @@
+# Validate Docker Swarm Stack
+
+Validate the Swarm stack named in `$ARGUMENTS`.
+
+If `$ARGUMENTS` is empty, inspect the repository and validate all stack YAML files you can safely validate.
+
+Steps:
+1. Identify the stack file and matching `.env.example` file.
+2. Run `docker compose config` with example env values when possible.
+3. Review for Swarm compatibility issues like `container_name`, local-only `depends_on` assumptions, and non-overlay networking.
+4. Report required Docker secrets, networks, volumes, and deployment command.
+5. Do not deploy or modify files unless the user asks.

.claude/skills/docker-swarm-stack.md

@@ -0,0 +1,32 @@
+# Docker Swarm Stack Skill
+
+Use this skill when adding, reviewing, or modifying Docker Swarm stack files in this repository.
+
+## Workflow
+
+1. Confirm the service belongs in the Swarm repo.
+2. Create or update a Swarm-compatible stack YAML file.
+3. Create or update `.env.example` with placeholders only.
+4. Use Docker secrets/configs for sensitive runtime values.
+5. Define overlay networks and named volumes explicitly.
+6. Add `deploy:` settings only when they are meaningful.
+7. Validate YAML/Compose rendering where possible.
+8. Explain deployment commands, required secrets, required networks, and rollback notes.
+
+## Swarm Standards
+
+- Use 2-space YAML indentation.
+- Prefer explicit image tags over unpinned `latest` when stability matters.
+- Use `deploy.restart_policy` for Swarm-managed services.
+- Use `placement.constraints` when a service must run on a specific node or node label.
+- Do not use `container_name`; it is ignored or problematic in Swarm.
+- Be careful with `depends_on`; Swarm does not honor Compose startup ordering the same way local Compose does.
+- Prefer external secrets for sensitive values.
+
+## Validation Command Pattern
+
+```bash
+docker compose --env-file <service>.env.example -f <stack-file>.yml config
+```
+
+Do not run `docker stack deploy` unless explicitly asked.

CLAUDE.md

@@ -0,0 +1,40 @@
+# Docker Swarm Services Repository
+
+This repository is for Docker Swarm stack files for Wheelz's HomeLab.
+
+## Repository Purpose
+
+- Store stack files intended for `docker stack deploy`.
+- Do not add regular non-Swarm Docker Compose stacks here.
+- Use this repo for services that are deployed to a Docker Swarm cluster.
+
+## Rules
+
+- Never commit real secrets, passwords, tokens, API keys, private keys, or recovery codes.
+- Use `.env.example` files and Docker secrets/config references for sensitive values.
+- Prefer Swarm-compatible Compose syntax. Avoid features that only work with local `docker compose` unless documented as unsupported in Swarm.
+- Use `deploy:` settings intentionally: replicas, placement constraints, restart policies, resources, labels, and update/rollback config where useful.
+- Use overlay networks for inter-service communication.
+- 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 Swarm stack files, syntax-check with:
+
+```bash
+docker compose --env-file <service>.env.example -f <service>-compose.yml config
+```
+
+Then review for Swarm compatibility before deployment with:
+
+```bash
+docker stack deploy -c <stack-file>.yml <stack-name>
+```
+
+Do not actually deploy unless the user explicitly asks.
+
+## Current Files
+
+- `claude-compose.yml` — Docker Swarm stack for Claude Code.
+- `claude.env.example` — example environment values for Claude Code stack.