build(wait0): expand Makefile automation and docs integration

Add strict Makefile preamble, self-documenting help, and standard dev/quality targets.

Add Docker lifecycle targets and a release target that runs scripts/publish.sh.

Update README and AGENTS command references to use canonical make workflows.

Author: mamchurovskyy

AGENTS.md

@@ -48,3 +48,16 @@ wait0 is an ultra-fast cache-first HTTP reverse proxy written in Go that serves
 |----------|------|-------------|
 | README | README.md | Project landing page and operational guide |
 | Docker Hub notes | DOCKERHUB.md | Alias to README for Docker Hub presentation |
+
+## Build & Development Commands
+This project uses a `Makefile` for build automation.
+
+Common commands:
+- `make help` — list all available targets
+- `make test` — run unit tests
+- `make test-race` — run race-enabled tests
+- `make coverage` — run coverage gate for `internal/wait0`
+- `make lint` — run static checks (`go vet`)
+- `make build` — build the `wait0` binary
+- `make ci-check` — run full local quality gate
+- `make docker-build` / `make docker-run` — build and run the container locally

Makefile

@@ -1,12 +1,99 @@
-.PHONY: test test-race coverage ci-check
+SHELL := bash
+.ONESHELL:
+.SHELLFLAGS := -eu -o pipefail -c
+.DELETE_ON_ERROR:
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rules
 
-test:
-	go test ./...
+GO ?= go
+PROJECT ?= $(notdir $(CURDIR))
+BIN_DIR ?= bin
+BINARY ?= wait0
+CMD_PACKAGE ?= ./cmd/wait0
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+BUILD_TIME := $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
 
-test-race:
-	go test -race ./...
+DOCKER ?= docker
+DOCKER_IMAGE ?= $(PROJECT)
+DOCKER_TAG ?= $(VERSION)
+CONTAINER_NAME ?= wait0-local
 
-coverage:
-	./scripts/coverage.sh 80
+COVERAGE_THRESHOLD ?= 80
 
-ci-check: test test-race coverage
+.DEFAULT_GOAL := help
+
+.PHONY: help build test test-race coverage lint fmt dev clean ci ci-check print-version \
+	docker-build docker-run docker-stop docker-logs docker-push docker-clean release
+
+help: ## Show available targets
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n"} \
+		/^[a-zA-Z0-9_.-]+:.*## / {printf "  \033[36m%-22s\033[0m %s\n", $$1, $$2} \
+		/^##@/ {printf "\n\033[1m%s\033[0m\n", substr($$0, 5)}' $(MAKEFILE_LIST)
+
+##@ Build
+build: ## Build wait0 binary
+	mkdir -p $(BIN_DIR)
+	$(GO) build -trimpath -o $(BIN_DIR)/$(BINARY) $(CMD_PACKAGE)
+
+print-version: ## Print build metadata
+	@echo "project=$(PROJECT)"
+	@echo "version=$(VERSION)"
+	@echo "commit=$(COMMIT)"
+	@echo "build_time=$(BUILD_TIME)"
+
+##@ Quality
+test: ## Run unit tests
+	$(GO) test ./...
+
+test-race: ## Run tests with race detector
+	$(GO) test -race ./...
+
+coverage: ## Run coverage gate for internal/wait0
+	./scripts/coverage.sh $(COVERAGE_THRESHOLD)
+
+lint: ## Run static checks
+	$(GO) vet ./...
+
+fmt: ## Format Go sources
+	$(GO) fmt ./...
+
+ci: lint test build ## Run fast CI checks (lint + test + build)
+
+ci-check: lint test test-race coverage build ## Run full local quality gate
+
+##@ Development
+dev: ## Run wait0 with debug config
+	$(GO) run $(CMD_PACKAGE) -config ./debug/wait0.yaml
+
+clean: ## Remove build and coverage artifacts
+	rm -rf $(BIN_DIR) coverage.out coverage.internal.filtered.out coverage-summary.txt
+
+##@ Docker
+docker-build: ## Build Docker image
+	$(DOCKER) build -t $(DOCKER_IMAGE):$(DOCKER_TAG) .
+
+docker-run: ## Run container with debug config and local data volume
+	mkdir -p .wait0-data
+	$(DOCKER) run -d --rm \
+		--name $(CONTAINER_NAME) \
+		-p 8082:8082 \
+		-v "$(CURDIR)/debug/wait0.yaml:/wait0.yaml:ro" \
+		-v "$(CURDIR)/.wait0-data:/data" \
+		$(DOCKER_IMAGE):$(DOCKER_TAG)
+
+docker-stop: ## Stop local container
+	-$(DOCKER) stop $(CONTAINER_NAME)
+
+docker-logs: ## Tail local container logs
+	$(DOCKER) logs -f $(CONTAINER_NAME)
+
+docker-push: ## Push Docker image to registry
+	$(DOCKER) push $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+docker-clean: ## Remove local Docker image
+	-$(DOCKER) image rm $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+##@ Publish
+release: ## Build and publish Docker image to Devforth DockerHub
+	./scripts/publish.sh

README.md

@@ -139,20 +139,27 @@ If you need to pre-warm cache after redeploy, it is recommended to use a sitemap
 How to run:
 
 ```bash
-go test ./...
+make test
 go run ./cmd/wait0 -config ./debug/wait0.yaml
 ```
 
 Testing and coverage gates:
 
 ```bash
-# full local quality gate (tests + race + coverage threshold)
+# show all available targets
+make help
+
+# full local quality gate (lint + tests + race + coverage threshold + build)
 make ci-check
 
-# or run separately
+# common commands
+make build
 make test
 make test-race
+make lint
+make fmt
 make coverage
+make dev
 ```
 
 Coverage policy:
@@ -161,6 +168,15 @@ Coverage policy:
   - `internal/wait0/proc_linux.go`
   - `internal/wait0/proc_other.go`
 
+Docker quick commands:
+
+```bash
+make docker-build
+make docker-run
+make docker-logs
+make docker-stop
+```
+
 Debug stack (origin + wait0):
 
 ```bash

publish.sh scripts/publish.shpublish.sh renamed to scripts/publish.sh

@@ -1,2 +1,2 @@
 docker buildx create --use
-docker buildx build --platform=linux/amd64,linux/arm64 --tag "devforth/wait0:latest" --tag "devforth/wait0:1.0.1" --push .
+docker buildx build --platform=linux/amd64,linux/arm64 --tag "devforth/wait0:latest" --tag "devforth/wait0:1.0.1" --push ../Dockerfile