CLAUDE.md

@@ -104,11 +104,20 @@ originating plan in `docs/plans/`, so the two files pair up 1:1. Create the file
 section per step after that, in chronological order (bottom of the file), not
 newest-first like `CHANGELOG.md`.
 
-Keep each entry light — a few sentences on what was done, plus anything genuinely
+Keep the prose light — a few sentences on what was done, plus anything genuinely
 interesting or non-obvious about how it went (a judgment call made, a spec gap found,
 something that didn't work as expected). This is not a duplicate of the plan or the
-diff; skip steps that went exactly as planned with nothing worth flagging. Commit the
+diff; skip steps that went exactly as planned with nothing worth flagging.
-summary update together with that step's implementation commit.
+
+**Include exact commands.** Any invocation of an external tool that isn't a plain file
+edit — CLI scaffolding tools (`kubebuilder`, code generators), package installs, other
+non-obvious shell commands — goes in as a fenced code block with the exact
+command-line actually run, not a paraphrase. Prefer the real invocation over a
+description of it; a future reader (or a future Claude) should be able to copy the
+snippet and reproduce the step. Trim noisy stdout, but keep anything that changed the
+outcome (a flag that mattered, an unexpected error, a version that got picked
+automatically). Commit the summary update together with that step's implementation
+commit.
 
 ### Changelog
 

docs/plans-executions/2026-08-07-1747-proxy-operator.md

@@ -4,16 +4,72 @@ Pairs with [docs/plans/2026-08-07-1747-proxy-operator.md](../plans/2026-08-07-17
 
 ## Step 0 — Branch and scaffold
 
-Branched `feat/proxy-operator` off the unborn `main`, installed kubebuilder v4.15.0
+Branched off the unborn `main`:
-via `go install`, and ran `kubebuilder init` + `kubebuilder create api` in place.
 
-Worth noting: `--domain example.com --group crawl` landed on the correct CRD group
+```bash
-(`crawl.example.com`) on the first try — the doubling trap the plan called out
+git checkout -b feat/proxy-operator
-(`--domain crawl.example.com --group crawl` → `crawl.crawl.example.com`) was avoided
+```
-by using the right flags from the start. `CONTROLLER_TOOLS_VERSION` came out at
+
-`v0.21.0` by default in this kubebuilder release, so no Makefile edit was needed there.
+Installed kubebuilder v4.15.0 into a scratch `GOBIN` rather than the default
-Dropped the scaffolded `.github/workflows/` since the remote is Gitea. Pre-existing
+`$(go env GOPATH)/bin`, since the module's package layout changed and
-`CLAUDE.md`/`CHANGELOG.md` content survived untouched; kubebuilder added its own
+`go install .../cmd/kubebuilder@v4.15.0` (the path from the plan) 404s — the binary is
-`README.md`, `AGENTS.md`, `.golangci.yml`, `.devcontainer/`, `Dockerfile` on top —
+now the module root itself:
-those get edited or left as-is in later steps. `go build ./...`, `go vet ./...`, and
+
-`make manifests generate` all ran clean. Committed as `076bc66`.
+```bash
+GOBIN=<scratch>/bin go install sigs.k8s.io/kubebuilder/v4@v4.15.0
+```
+
+Scaffolded in place, with `kubebuilder` on `PATH`:
+
+```bash
+kubebuilder version
+# KubeBuilder: v4.15.0, Kubernetes: 1.36.0
+
+kubebuilder init --domain example.com \
+  --repo gitea.home.hrajfrisbee.cz/kacerr/egress-proxies-operator --plugins go/v4
+# WARN: target directory not empty (expected — CLAUDE.md, docs/, .claude/ already existed)
+
+kubebuilder create api --group crawl --version v1alpha1 --kind Proxy \
+  --resource --controller
+```
+
+`create api` auto-ran `make manifests` at the end, which pulled and ran
+`controller-gen` itself:
+
+```bash
+sigs.k8s.io/controller-tools/cmd/controller-gen@v0.21.0
+"$(bin)/controller-gen" object:headerFile="hack/boilerplate.go.txt",year=2026 paths="./..."
+```
+
+Confirmed the CRD group landed correctly (no doubling — `--domain example.com
+--group crawl` was used specifically to avoid the `crawl.crawl.example.com` trap
+called out in the plan):
+
+```bash
+grep -A2 "GroupVersion =" api/v1alpha1/groupversion_info.go
+# SchemeGroupVersion = schema.GroupVersion{Group: "crawl.example.com", Version: "v1alpha1"}
+```
+
+Dropped the scaffolded GitHub Actions workflows (remote is Gitea, not GitHub):
+
+```bash
+git rm -r --cached .github 2>/dev/null; rm -rf .github
+```
+
+Ran the full manifest/codegen pass once more to confirm the toolchain is reproducible
+end to end:
+
+```bash
+make manifests generate
+# controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+# controller-gen object:headerFile="hack/boilerplate.go.txt",year=2026 paths="./..."
+```
+
+then `go build ./...` and `go vet ./...`, both clean with no output.
+
+Worth noting: `CONTROLLER_TOOLS_VERSION` in the generated `Makefile` came out at
+`v0.21.0` by default in this kubebuilder release, so the Makefile edit the plan
+anticipated wasn't needed. Pre-existing `CLAUDE.md`/`CHANGELOG.md` content survived
+untouched; kubebuilder added its own `README.md`, `AGENTS.md`, `.golangci.yml`,
+`.devcontainer/`, `Dockerfile` on top of them — those get edited or left as-is in
+later steps. Committed as `076bc66`.