Add pre-commit hooks, Makefile, dev container, agent guide and CI

[mainman94]

This repo has no CI deploy — stacks come up on the host — so a mistake in a compose file was previously only caught when something failed to start. This adds the local and CI checks that catch it earlier.

What's in it

• .pre-commit-config.yaml — hygiene, yamlfmt, shellcheck, shfmt, gitleaks, plus two repo-specific hooks.
• Makefile — make help lists everything; make check is the gate.
• .devcontainer/ — Docker, Python, trivy, jq and the hook toolchain.
• AGENTS.md — existing conventions kept verbatim, plus workflow and scanning sections.
• .github/workflows/ci.yml — every hook on each PR.
• .github/workflows/scan.yml — weekly trivy sweep of all 47 referenced images.

The two repo-specific hooks

compose-config runs docker compose config per stack. The real .env and backup.env are host-only, so each stack is validated in a scratch copy holding just the compose file and its env files, with <name>.example materialised as <name>. Nothing is written into the worktree.

stack-conventions checks the AGENTS.md rules that are cheap to verify statically: the default network is named <stack>_network, and every mandatory ${VAR} has a key in that stack's .env.example. ${VAR:-default} is optional by construction and exempt.

paperless-ngx and pocket-id are grandfathered on the network rule — renaming a live network restarts everything attached to it, which is a deploy decision, not a lint fix. Worth a look if you'd rather do the rename.

Worth reviewing

• infrastructure/volume-backup/backup.env holds the Backblaze credentials and was never gitignored. Now is.
• CDPATH= → CDPATH='' in check-backup-paths.sh — identical to the shell, no longer trips shellcheck SC1007.
• .yamlfmt uses scan_folded_as_literal so the folded command: blocks keep one flag per line. It reformats nothing in the current tree.
• Application config under <stack>/config/ is excluded from yamlfmt and check-yaml — it follows each app's own format, and recyclarr's uses a custom !env_var tag.

The image sweep is advisory on purpose

These are other people's images; a new upstream CVE isn't something a commit here can fix, and a red build nobody can clear is a build people stop reading. --ignore-unfixed for the same reason. make scan-strict exits non-zero on fixable CRITICALs if you ever want a gate.

Renovate already moves the digest pins, so the usual fix for a finding is to let it bump the image.

Test plan

• pre-commit run --all-files passes on the full tree; all 30 compose files validate and all 29 stacks pass the convention check.
• Both hooks were negative-tested against a deliberately broken stack.
• Workflows are actionlint-clean.
• Not run here: the trivy sweep — the sandbox proxy blocks the Trivy DB. Worth a manual workflow_dispatch before trusting the weekly schedule; 47 third-party images is where the backlog is most likely to be non-trivial.

🤖 Generated with Claude Code

https://claude.ai/code/session_0134YCw5jnsz4cXPAPN5rHhN

---

Generated by Claude Code