diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..7646fe3f
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,52 @@
+# Compiled Object files, Static and Dynamic libs (Shared Objects)
+*.o
+*.a
+*.so
+
+# Folders
+_obj
+_test
+
+# IntelliJ
+.idea
+# Goland's output filename can not be set manually
+/go_build_*
+
+# MS VSCode
+.vscode
+__debug_bin*
+
+# Architecture specific extensions/prefixes
+*.[568vq]
+[568vq].out
+
+*.cgo1.go
+*.cgo2.c
+_cgo_defun.c
+_cgo_gotypes.go
+_cgo_export.*
+
+_testmain.go
+
+*.exe
+*.test
+*.prof
+
+*coverage.out
+coverage.all
+coverage.txt
+cpu.out
+
+*.db
+*.log
+
+/act_runner
+/debug
+
+/bin
+/dist
+/.env
+/.runner
+/config.yaml
+/Dockerfile
+.DS_Store
diff --git a/.editorconfig b/.editorconfig
index deec24a1..41e1f4f9 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -12,5 +12,8 @@ insert_final_newline = true
 [*.{go}]
 indent_style = tab
 
+[go.*]
+indent_style = tab
+
 [Makefile]
 indent_style = tab
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..97d1e0c0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,10 @@
+- Use `make help` to find available development targets
+- Run `make fmt` to format `.go` files, and run `make lint-go` to lint them
+- Run `make tidy` after any `go.mod` changes
+- Run single go unit tests with `go test -run '^TestName$' ./modulepath/`
+- Add the current year into the copyright header of new `.go` files
+- Ensure no trailing whitespace in edited files
+- Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates
+- Preserve existing code comments, do not remove or rewrite comments that are still relevant
+- Include authorship attribution in issue and pull request comments
+- Add `Co-Authored-By` lines to all commits, indicating name and model used
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..43c994c2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/Makefile b/Makefile
index 0b88b2d4..c0e5b284 100644
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,7 @@ SHASUM ?= shasum -a 256
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
 XGO_PACKAGE ?= src.techknowlogick.com/xgo@latest
 XGO_VERSION := go-1.26.x
-GXZ_PAGAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.10
+GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.10
 
 LINUX_ARCHS ?= linux/amd64,linux/arm64
 DARWIN_ARCHS ?= darwin-12/amd64,darwin-12/arm64
@@ -21,10 +21,10 @@ DOCKER_ROOTLESS_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)-dind-rootless
 GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.11.4
 GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1
 
-ifneq ($(shell uname), Darwin)
-	EXTLDFLAGS = -extldflags "-static" $(null)
-else
-	EXTLDFLAGS =
+STATIC ?=
+EXTLDFLAGS ?=
+ifneq ($(STATIC),)
+	EXTLDFLAGS = -extldflags "-static"
 endif
 
 ifeq ($(HAS_GO), GO)
@@ -69,10 +69,15 @@ endif
 TAGS ?=
 LDFLAGS ?= -X "gitea.com/gitea/act_runner/internal/pkg/ver.version=v$(RELASE_VERSION)"
 
+.PHONY: all
 all: build
 
+.PHONY: help
+help: Makefile ## print Makefile help information.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m[TARGETS] default target: build\033[0m\n\n\033[35mTargets:\033[0m\n"} /^[0-9A-Za-z._-]+:.*?##/ { printf "  \033[36m%-45s\033[0m %s\n", $$1, $$2 }' Makefile
+
 .PHONY: fmt
-fmt:
+fmt: ## format the Go code
 	$(GO) run $(GOLANGCI_LINT_PACKAGE) fmt
 
 .PHONY: go-check
@@ -96,10 +101,14 @@ fmt-check: fmt
 
 .PHONY: deps-tools
 deps-tools: ## install tool dependencies
-	$(GO) install $(GOVULNCHECK_PACKAGE)
+	$(GO) install $(GOLANGCI_LINT_PACKAGE) & \
+	$(GO) install $(GXZ_PACKAGE) & \
+	$(GO) install $(XGO_PACKAGE) & \
+	$(GO) install $(GOVULNCHECK_PACKAGE) & \
+	wait
 
 .PHONY: lint
-lint: lint-go
+lint: lint-go ## lint everything
 
 .PHONY: lint-go
 lint-go: ## lint go files
@@ -114,58 +123,59 @@ security-check: deps-tools
 	GOEXPERIMENT= $(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
 
 .PHONY: tidy
-tidy:
+tidy: ## run go mod tidy
 	$(GO) mod tidy
 
 .PHONY: tidy-check
 tidy-check: tidy
-	@diff=$$(git diff -- go.mod go.sum); \
+	@diff=$$(git diff --color=always -- go.mod go.sum); \
 	if [ -n "$$diff" ]; then \
 		echo "Please run 'make tidy' and commit the result:"; \
-		echo "$${diff}"; \
+		printf "%s" "$${diff}"; \
 		exit 1; \
 	fi
 
-test: fmt-check security-check
+.PHONY: test
+test: fmt-check security-check ## test everything
 	@$(GO) test -race -short -v -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
 
-install: $(GOFILES)
-	$(GO) install -v -tags '$(TAGS)' -ldflags '$(EXTLDFLAGS)-s -w $(LDFLAGS)'
+.PHONY: install
+install: $(GOFILES) ## install the act_runner binary via `go install`
+	$(GO) install -v -tags '$(TAGS)' -ldflags '-s -w $(EXTLDFLAGS) $(LDFLAGS)'
 
-build: go-check $(EXECUTABLE)
+.PHONY: build
+build: go-check $(EXECUTABLE) ## build the act_runner binary
 
 $(EXECUTABLE): $(GOFILES)
-	$(GO) build -v -tags '$(TAGS)' -ldflags '$(EXTLDFLAGS)-s -w $(LDFLAGS)' -o $@
+	$(GO) build -v -tags '$(TAGS)' -ldflags '-s -w $(EXTLDFLAGS) $(LDFLAGS)' -o $@
 
 .PHONY: deps-backend
-deps-backend:
+deps-backend: ## install backend dependencies
 	$(GO) mod download
-	$(GO) install $(GXZ_PAGAGE)
-	$(GO) install $(XGO_PACKAGE)
 
 .PHONY: release
-release: release-windows release-linux release-darwin release-copy release-compress release-check
+release: release-windows release-linux release-darwin release-copy release-compress release-check ## build release artifacts
 
 $(DIST_DIRS):
 	mkdir -p $(DIST_DIRS)
 
 .PHONY: release-windows
 release-windows: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -buildmode exe -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(WINDOWS_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
+	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -buildmode exe -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w -linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(WINDOWS_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
 ifeq ($(CI),true)
 	cp -r /build/* $(DIST)/binaries/
 endif
 
 .PHONY: release-linux
 release-linux: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(LINUX_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
+	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w -linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(LINUX_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
 ifeq ($(CI),true)
 	cp -r /build/* $(DIST)/binaries/
 endif
 
 .PHONY: release-darwin
 release-darwin: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '$(LDFLAGS)' -targets '$(DARWIN_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
+	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w $(LDFLAGS)' -targets '$(DARWIN_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
 ifeq ($(CI),true)
 	cp -r /build/* $(DIST)/binaries/
 endif
@@ -180,18 +190,20 @@ release-check: | $(DIST_DIRS)
 
 .PHONY: release-compress
 release-compress: | $(DIST_DIRS)
-	cd $(DIST)/release/; for file in `find . -type f -name "*"`; do echo "compressing $${file}" && $(GO) run $(GXZ_PAGAGE) -k -9 $${file}; done;
+	cd $(DIST)/release/; for file in `find . -type f -name "*"`; do echo "compressing $${file}" && $(GO) run $(GXZ_PACKAGE) -k -9 $${file}; done;
 
 .PHONY: docker
-docker:
+docker: ## build the docker image
 	if ! docker buildx version >/dev/null 2>&1; then \
 		ARG_DISABLE_CONTENT_TRUST=--disable-content-trust=false; \
 	fi; \
 	docker build $${ARG_DISABLE_CONTENT_TRUST} -t $(DOCKER_REF) .
 
-clean:
+.PHONY: clean
+clean: ## delete binary and coverage files
 	$(GO) clean -x -i ./...
 	rm -rf coverage.txt $(EXECUTABLE) $(DIST)
 
-version:
+.PHONY: version
+version: ## print the version
 	@echo $(VERSION)