docs: expand README

README.md

@@ -1,3 +1,54 @@
 # setup-buildx
 
-Composite action: docker/setup-buildx-action wired to the in-cluster buildkit service
+Drop-in replacement for `docker/setup-buildx-action@v3` that defaults to the
+in-cluster `buildkit.gitea.svc.cluster.local:1234` service in the aceofbase
+cluster.
+
+Use this whenever a Gitea Actions workflow needs to build images. It removes
+the boilerplate of declaring a remote driver every time, and ensures every
+build reuses the cluster's BuildKit + the GitHub Actions cache server
+(`gha-cache-server`) for layer caching.
+
+## Usage
+
+```yaml
+jobs:
+  build:
+    runs-on: aceofba-cluster
+    container:
+      image: ghcr.io/catthehacker/ubuntu:act-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: https://git.aceofba.se/logaritmisk/setup-buildx@v1
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          tags: git.aceofba.se/${{ github.repository }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+## Inputs
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `endpoint` | `tcp://buildkit.gitea.svc.cluster.local:1234` | BuildKit TCP endpoint. Override only if you run a private buildkit somewhere else. |
+| `install` | `false` | Set up `docker build` as alias to `docker buildx build`. |
+| `version` | `latest` | buildx version, passed through to the upstream action. |
+
+## Why
+
+`docker/setup-buildx-action@v3` defaults to `driver: docker-container`, which
+requires a working Docker daemon inside the job container. The act-runner
+uses Kubernetes pod-per-job hooks — there is no dockerd in those pods. The
+cluster does run a standalone BuildKit Service (`buildkit-service` Helm
+chart, port 1234) which buildx can talk to via its `remote` driver. This
+action wires that in by default.
+
+The per-job runner pod already exports `ACTIONS_CACHE_URL` /
+`ACTIONS_RUNTIME_TOKEN` pointing at `gha-cache-server`, so `cache-from`/
+`cache-to: type=gha` works without any extra config.