# AGENTS.md: Docker and Compose

## Commands
- `docker compose up --build -d` · `docker compose logs -f <svc>` · `docker compose down` (no `-v` unless asked)
- Lint: `hadolint Dockerfile` if available. Scan: `docker scout cves <image>` or `trivy image <image>`.

## Dockerfiles
- Multi-stage builds: a `build` stage with dev deps, a small runtime stage (`-slim`, `distroless`, or `alpine` if the stack supports musl).
- Pin base images to a specific version tag (e.g. `node:22.11-slim`), not `latest`.
- Order layers for caching: copy lockfiles, install deps, then copy source. Use `RUN --mount=type=cache` for package caches.
- Maintain `.dockerignore` (`.git`, `node_modules`, `.env`, build output).
- Run as a non-root `USER`. Add a `HEALTHCHECK` or a compose `healthcheck`.
- One process per container; use exec-form `CMD ["node","server.js"]` so signals reach it.
- No secrets in `ENV`, `ARG`, or copied files; use build secrets (`--mount=type=secret`) or runtime env.

## Compose
- File is `compose.yaml`; no top-level `version:` key.
- Services depend with `depends_on: { db: { condition: service_healthy } }`.
- Config through `env_file: .env` (gitignored) with a committed `.env.example`.
- Named volumes for data; bind mounts only for source in dev. Use `develop.watch` for live sync if set up.

## Done
Image builds, `docker compose up` reaches healthy, and the image size is noted in the summary.