docs: add agents documentation and CI validation instructions (#696)

* docs: add agents documentation and CI validation instructions

* docs: correct ShellCheck capitalization and update error message in Makefile

Author: ilopezluna

AGENTS.md

@@ -0,0 +1,33 @@
+# Agents
+
+## Before committing
+
+Run all CI validations locally before committing changes:
+
+```
+make validate-all
+```
+
+This runs the same checks as CI:
+
+1. **go mod tidy** — ensures `go.mod`/`go.sum` are clean
+2. **Lint** — runs `golangci-lint` (see [`.golangci.yml`](./.golangci.yml) for configuration)
+3. **Tests** — runs all unit tests with race detection (`go test -race ./...`)
+4. **ShellCheck** — validates all shell scripts
+
+If any step fails, fix the issue and re-run before committing.
+
+### Prerequisites
+
+- **Go 1.25.6+**
+- **golangci-lint v2.7.2+** — [Install instructions](https://golangci-lint.run/welcome/install/)
+- **ShellCheck** — `brew install shellcheck` (macOS) or `apt-get install shellcheck` (Linux)
+
+## Project documentation
+
+- [README.md](./README.md) — project overview, building from source, API examples, and Makefile usage
+- [METRICS.md](./METRICS.md) — aggregated metrics endpoint documentation
+- [Model CLI README](./cmd/cli/README.md) — CLI plugin (`docker model`) documentation
+- [Helm chart](./charts/docker-model-runner/README.md) — Kubernetes deployment guide
+- [Model Specification](https://github.com/docker/model-spec/blob/main/spec.md) — model packaging specification
+- [Docker Docs](https://docs.docker.com/ai/model-runner/get-started/) — official Docker Model Runner documentation

Makefile

@@ -26,7 +26,7 @@ DOCKER_BUILD_ARGS := \
 BUILD_DMR ?= 1
 
 # Main targets
-.PHONY: build run clean test integration-tests test-docker-ce-installation docker-build docker-build-multiplatform docker-run docker-build-vllm docker-run-vllm docker-build-sglang docker-run-sglang docker-run-impl help validate lint docker-build-diffusers docker-run-diffusers vllm-metal-build vllm-metal-install vllm-metal-dev vllm-metal-clean build-cli install-cli
+.PHONY: build run clean test integration-tests test-docker-ce-installation docker-build docker-build-multiplatform docker-run docker-build-vllm docker-run-vllm docker-build-sglang docker-run-sglang docker-run-impl help validate validate-all lint docker-build-diffusers docker-run-diffusers vllm-metal-build vllm-metal-install vllm-metal-dev vllm-metal-clean build-cli install-cli
 # Default target
 .DEFAULT_GOAL := build
 
@@ -89,6 +89,25 @@ lint:
 	golangci-lint run ./...
 	@echo "✓ Go linting passed!"
 
+# Run all CI validations locally (use before committing)
+validate-all:
+	@echo "==> Checking go mod tidy..."
+	@go mod tidy
+	@git diff --exit-code go.mod go.sum || (echo "ERROR: go.mod/go.sum were not tidy. The files have been updated — please commit the changes." && exit 1)
+	@echo "✓ go.mod is tidy"
+	@echo ""
+	@echo "==> Running linter..."
+	@$(MAKE) lint
+	@echo ""
+	@echo "==> Running tests with race detection..."
+	@go test -race ./...
+	@echo "✓ All tests passed!"
+	@echo ""
+	@echo "==> Running shellcheck validation..."
+	@$(MAKE) validate
+	@echo ""
+	@echo "==> All validations passed! ✅"
+
 # Build Docker image
 docker-build:
 	docker buildx build $(DOCKER_BUILD_ARGS) .
@@ -226,12 +245,16 @@ vllm-metal-clean:
 help:
 	@echo "Available targets:"
 	@echo "  build				- Build the Go application"
+	@echo "  build-cli			- Build the CLI (docker-model plugin)"
+	@echo "  install-cli			- Build and install the CLI as a Docker plugin"
+	@echo "  docs				- Generate CLI documentation"
 	@echo "  run				- Run the application locally"
 	@echo "  clean				- Clean build artifacts"
 	@echo "  test				- Run tests"
-	@echo "  integration-tests		- Run integration tests"
+	@echo "  integration-tests		- Run integration tests (requires Docker)"
 	@echo "  test-docker-ce-installation	- Test Docker CE installation with CLI plugin"
 	@echo "  validate			- Run shellcheck validation"
+	@echo "  validate-all			- Run all CI validations locally (lint, test, shellcheck, go mod tidy)"
 	@echo "  lint				- Run Go linting with golangci-lint"
 	@echo "  docker-build			- Build Docker image for current platform"
 	@echo "  docker-build-multiplatform	- Build Docker image for multiple platforms"

README.md

@@ -176,16 +176,23 @@ MODEL_RUNNER_HOST=http://localhost:13434 ./model-cli list
 
 ## Using the Makefile
 
-This project includes a Makefile to simplify common development tasks. It requires Docker Desktop >= 4.41.0
-The Makefile provides the following targets:
+This project includes a Makefile to simplify common development tasks. Docker targets require Docker Desktop >= 4.41.0.
+Run `make help` for a full list, but the key targets are:
 
 - `build` - Build the Go application
+- `build-cli` - Build the CLI (`docker-model` plugin)
+- `install-cli` - Build and install the CLI as a Docker plugin
+- `docs` - Generate CLI documentation
 - `run` - Run the application locally
 - `clean` - Clean build artifacts
 - `test` - Run tests
-- `docker-build` - Build the Docker image
+- `validate-all` - **Run all CI validations locally** (lint, test, shellcheck, go mod tidy)
+- `lint` - Run Go linting with golangci-lint
+- `validate` - Run shellcheck validation on shell scripts
+- `integration-tests` - Run integration tests (requires Docker)
+- `docker-build` - Build the Docker image for current platform
 - `docker-run` - Run the application in a Docker container with TCP port access and mounted model storage
-- `help` - Show available targets
+- `help` - Show all available targets and configuration options
 
 ### Running in Docker