Docs overhaul: cleanup, fixes, and improvements

.github/workflows/playwright.yml

@@ -0,0 +1,56 @@
+name: Playwright Tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@b90be12699fdfcbee4440c2bba85f6f460446bb0 # v1.279.0
+        with:
+          ruby-version: "3.1"
+          bundler-cache: true
+
+      - name: Build Jekyll site
+        run: bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+          PAGES_REPO_NWO: go-coldbrew/docs.coldbrew.cloud
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install chromium
+
+      - name: Run Playwright tests
+        run: npx playwright test
+        env:
+          CI: true
+
+      - name: Upload test report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14

.gitignore

@@ -1 +1,4 @@
 _site
+node_modules
+test-results
+playwright-report

FAQ.md

@@ -128,10 +128,14 @@ You can register cleanup callbacks and customize shutdown behavior. See the [Sig
 Set the `SENTRY_DSN` environment variable and use the errors package:
 
 ```go
-import "github.com/go-coldbrew/errors"
+import (
+    "context"
+    "github.com/go-coldbrew/errors/notifier"
+)
 
 // This notifies Sentry asynchronously (bounded, won't leak goroutines)
-errors.NotifyAsync(err, severity, args...)
+ctx := context.Background()
+notifier.Notify(err, ctx)
 ```
 
 See the [Errors How-To](/howto/errors) and [Integrations](/integrations) for full setup instructions.

Gemfile

@@ -7,3 +7,10 @@ gem "jekyll-github-metadata", ">= 2.15"
 gem "webrick", "~> 1.7"
 gem 'jekyll-target-blank'
 gem "jekyll-sitemap"
+
+# Required for Ruby 4.0+ (removed from default gems)
+gem "logger"
+gem "csv"
+gem "ostruct"
+gem "base64"
+gem "bigdecimal"

Gemfile.lock

@@ -3,8 +3,11 @@ GEM
   specs:
     addressable (2.8.4)
       public_suffix (>= 2.0.2, < 6.0)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
     colorator (1.1.0)
     concurrent-ruby (1.2.2)
+    csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
@@ -15,9 +18,7 @@ GEM
     faraday-net_http (3.0.2)
     ffi (1.15.5)
     forwardable-extended (2.6.0)
-    google-protobuf (3.22.3-arm64-darwin)
-    google-protobuf (3.22.3-x86_64-darwin)
-    google-protobuf (3.22.3-x86_64-linux)
+    google-protobuf (3.22.3)
     http_parser.rb (0.8.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
@@ -65,16 +66,16 @@ GEM
     listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     mercenary (0.4.0)
-    nokogiri (1.13.10-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.13.10-x86_64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.13.10-x86_64-linux)
+    mini_portile2 (2.8.9)
+    nokogiri (1.13.10)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     octokit (4.25.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
+    ostruct (0.6.3)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (5.0.1)
@@ -87,9 +88,12 @@ GEM
     rouge (3.30.0)
     ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.58.3)
+    sass-embedded (1.58.3-arm64-darwin)
+      google-protobuf (~> 3.21)
+    sass-embedded (1.58.3-x86_64-darwin)
+      google-protobuf (~> 3.21)
+    sass-embedded (1.58.3-x86_64-linux-gnu)
       google-protobuf (~> 3.21)
-      rake (>= 10.0.0)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
@@ -100,16 +104,22 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  arm64-darwin-25
   x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES
+  base64
+  bigdecimal
+  csv
   jekyll (~> 4.3)
   jekyll-default-layout
   jekyll-github-metadata (>= 2.15)
   jekyll-sitemap
   jekyll-target-blank
   just-the-docs (= 0.5.0)
+  logger
+  ostruct
   webrick (~> 1.7)
 
 BUNDLED WITH

Index.md

@@ -55,8 +55,8 @@ Your service starts with all of these endpoints ready:
 | `localhost:9090` | gRPC server |
 | `localhost:9091` | HTTP/REST gateway (auto-mapped from gRPC) |
 | `localhost:9091/metrics` | Prometheus metrics |
-| `localhost:9091/healthcheck` | Kubernetes liveness probe |
-| `localhost:9091/readycheck` | Kubernetes readiness probe |
+| `localhost:9091/healthcheck` | Liveness probe — returns build/version info as JSON |
+| `localhost:9091/readycheck` | Readiness probe — returns version JSON when ready |
 | `localhost:9091/swagger/` | Swagger UI |
 | `localhost:9091/debug/pprof/` | Go pprof profiling |
 

Packages.md

@@ -3,6 +3,7 @@ layout: default
 title: Packages
 description: "ColdBrew packages documentation"
 permalink: /packages
+nav_order: 9
 ---
 # Packages
 {: .no_toc }
@@ -19,7 +20,7 @@ The core module is the base module and provides the base implementation for Cold
 Documentation can be found at [core-docs]
 
 ### [Config]
-Coldbrew config package contains the configuration for the core package. It uses [envconfig] to load the configuration from the environment variables.
+ColdBrew config package contains the configuration for the core package. It uses [envconfig] to load the configuration from the environment variables.
 
 Documentation can be found at [config-docs]
 
@@ -85,3 +86,4 @@ Documentation can be found at [data-builder-docs]
 [grpcpool-docs]: https://pkg.go.dev/github.com/go-coldbrew/grpcpool
 [Data Builder]: https://github.com/go-coldbrew/data-builder/tree/main#readme
 [data-builder-docs]: https://pkg.go.dev/github.com/go-coldbrew/data-builder
+[envconfig]: https://github.com/kelseyhightower/envconfig

USING.md

@@ -23,12 +23,19 @@ A ColdBrew project generated from the [cookiecutter template](https://github.com
 ```
 MyApp/
   proto/              # Protocol buffer definitions
-    helloworld.proto
-  server/             # gRPC service implementation
-    server.go
+    myapp.proto
+  service/            # gRPC service implementation
+    service.go
+    service_test.go
+    healthcheck.go
+    healthcheck_test.go
+  config/
+    config.go         # Configuration via environment variables
+  version/
+    version.go        # Build-time version info
   main.go             # Entry point
-  Makefile             # Build, test, lint, run targets
-  Dockerfile           # Production container
+  Makefile            # Build, test, lint, run targets
+  Dockerfile          # Production container
   go.mod
 ```
 
@@ -51,12 +58,12 @@ The `google.api.http` annotation automatically creates a REST endpoint via grpc-
 After editing your proto file, regenerate the Go code:
 
 ```shell
-make gen
+make generate
 ```
 
 ## Implementing Your Service
 
-Implement the generated gRPC interface in your `server/server.go`:
+Implement the generated gRPC interface in your `service/service.go`:
 
 ```go
 func (s *svcNameImpl) SayHello(ctx context.Context, req *pb.SayHelloRequest) (*pb.SayHelloResponse, error) {

_config.yml

@@ -21,6 +21,8 @@ defaults:
 
 permalink: pretty
 
+search_enabled: true
+
 theme: just-the-docs
 
 callouts_level: quiet

architecture.md

@@ -216,8 +216,9 @@ A typical ColdBrew service exposes two ports:
 
 ColdBrew is designed for Kubernetes deployments:
 
-- **Liveness probe:** `GET /healthcheck` — returns `SERVING` when healthy
-- **Readiness probe:** `GET /readycheck` — returns `SERVING` when ready for traffic
+- **Liveness probe:** `GET /healthcheck` — returns build/version info as JSON (git commit, version, build date, Go version, OS/arch)
+- **Readiness probe:** `GET /readycheck` — returns the same version JSON when ready for traffic, or an error if the service hasn't called `SetReady()` yet
+- **gRPC health protocol:** Implements `grpc.health.v1.Health` ([standard gRPC health checking](https://github.com/grpc/grpc/blob/master/doc/health-checking.md)) on the gRPC port — used by gRPC load balancers, Envoy, Istio, and other service meshes for native health checking
 - **Graceful shutdown:** On SIGTERM, the service marks itself as not ready, drains in-flight requests, then exits cleanly
 - **Metrics scraping:** Prometheus scrapes `/metrics` on the HTTP port
 

data-builder-example/go.mod

@@ -1,6 +1,6 @@
 module example
 
-go 1.19
+go 1.25.0
 
 require github.com/go-coldbrew/data-builder v0.0.11
 
@@ -9,16 +9,16 @@ require (
 	github.com/go-coldbrew/tracing v0.0.1 // indirect
 	github.com/goccy/go-graphviz v0.0.9 // indirect
 	github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0 // indirect
-	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/newrelic/go-agent/v3 v3.9.0 // indirect
 	github.com/opentracing/opentracing-go v1.2.0 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
-	golang.org/x/image v0.0.0-20200119044424-58c23975cae1 // indirect
-	golang.org/x/net v0.8.0 // indirect
-	golang.org/x/sys v0.6.0 // indirect
-	golang.org/x/text v0.8.0 // indirect
+	golang.org/x/image v0.38.0 // indirect
+	golang.org/x/net v0.52.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/text v0.35.0 // indirect
 	google.golang.org/genproto v0.0.0-20220519153652-3a47de7e79bd // indirect
-	google.golang.org/grpc v1.46.2 // indirect
-	google.golang.org/protobuf v1.28.0 // indirect
+	google.golang.org/grpc v1.79.3 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 	k8s.io/apimachinery v0.23.3 // indirect
 )