feat: add CI/release automation and complete SDK implementation

- Add Forgejo CI workflow: gofmt checks, module caching, coverage reporting
- Add release workflow: auto-tag-triggered release with changelog extraction
- Update module paths from rock/ to homelab/ namespace
- Enhance test coverage and documentation (PLAN.md, README.md)

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

.forgejo/workflows/ci.yaml

@@ -2,8 +2,13 @@ name: ci
 
 on:
   push:
+    branches: [main]
   pull_request:
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: docker
@@ -11,14 +16,55 @@ jobs:
       image: golang:1.25
     env:
       GOPRIVATE: forgejo.riotpiao.homelab.com
+      GOFLAGS: -mod=readonly
     steps:
+      # actions/checkout is a Node-based action; golang:1.25 has no node on PATH.
+      - name: install node (required by JS-based actions)
+        run: apt-get update && apt-get install -y --no-install-recommends nodejs ca-certificates git
+
       - uses: actions/checkout@v4
 
-      - name: go build
-        run: go build ./...
+      # kmsvc-proto lives in another private repo on the same Forgejo instance.
+      # FORGEJO_PAT needs read access to that repo; without it `go build` 404s on go-get.
+      - name: configure git auth for private module fetch
+        run: |
+          git config --global url."https://oauth2:${FORGEJO_PAT}@forgejo.riotpiao.homelab.com".insteadOf "https://forgejo.riotpiao.homelab.com"
+        env:
+          FORGEJO_PAT: ${{ secrets.FORGEJO_PAT }}
+
+      - name: cache go modules + build cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: go-${{ runner.os }}-${{ hashFiles('go.sum') }}
+          restore-keys: |
+            go-${{ runner.os }}-
+
+      - name: gofmt
+        run: |
+          fmt_out="$(gofmt -l .)"
+          if [ -n "$fmt_out" ]; then
+            echo "$fmt_out"
+            echo "::error::gofmt found unformatted files, run 'gofmt -w .'"
+            exit 1
+          fi
 
       - name: go vet
         run: go vet ./...
 
+      - name: go build
+        run: go build ./...
+
       - name: go test
-        run: go test ./... -race
+        run: go test ./... -race -coverprofile=coverage.out
+
+      - name: coverage summary
+        run: go tool cover -func=coverage.out | tail -1
+
+      - name: upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.out

.forgejo/workflows/release.yaml

@@ -0,0 +1,71 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: docker
+    container:
+      image: golang:1.25
+    env:
+      GOPRIVATE: forgejo.riotpiao.homelab.com
+    steps:
+      - name: install node + curl + jq (required by JS-based actions / release API call)
+        run: apt-get update && apt-get install -y --no-install-recommends nodejs ca-certificates git curl jq
+
+      - uses: actions/checkout@v4
+
+      - name: configure git auth for private module fetch
+        run: |
+          git config --global url."https://oauth2:${FORGEJO_PAT}@forgejo.riotpiao.homelab.com".insteadOf "https://forgejo.riotpiao.homelab.com"
+        env:
+          FORGEJO_PAT: ${{ secrets.FORGEJO_PAT }}
+
+      # A tag is the public contract for `go get [email protected]` — re-run the full
+      # gate before publishing a release, never trust that main was green.
+      - name: go vet
+        run: go vet ./...
+
+      - name: go build
+        run: go build ./...
+
+      - name: go test
+        run: go test ./... -race
+
+      - name: extract changelog section
+        id: changelog
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          version="${tag#v}"
+          notes="$(awk -v ver="$version" '
+            $0 ~ "^## v"ver"([^.0-9]|$)" { found=1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md)"
+          if [ -z "$notes" ]; then
+            notes="(no changelog entry found for $tag)"
+          fi
+          {
+            echo "notes<<EOF"
+            echo "$notes"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: create forgejo release
+        run: |
+          curl -fsSL -X POST \
+            -H "Authorization: token ${FORGEJO_TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/releases" \
+            -d "$(jq -n \
+                  --arg tag "$GITHUB_REF_NAME" \
+                  --arg body "${{ steps.changelog.outputs.notes }}" \
+                  '{tag_name: $tag, name: $tag, body: $body, draft: false, prerelease: false}')"
+        env:
+          FORGEJO_TOKEN: ${{ secrets.GITHUB_TOKEN }}