docs: strip over-commenting from README and source

README.md

@@ -55,12 +55,10 @@ unknown fields survive untouched.
 
 Precedence (lowest → highest): **defaults < config file < env vars (`PDBMUX_*`) < flags**.
 
-Config file: `$XDG_CONFIG_HOME/pdbmux/config.yaml`. In Kubernetes, configuration
-is supplied entirely via `PDBMUX_*` env vars (no config file), which is the
-supported deployment path — see [Deployment](#deployment).
+Config file: `$XDG_CONFIG_HOME/pdbmux/config.yaml`. In Kubernetes there is no
+config file — everything comes from `PDBMUX_*` env vars.
 
 ```yaml
-# ~/.config/pdbmux/config.yaml  (local dev; in k8s use PDBMUX_* env instead)
 listen: ":8080"
 backends:
   - name: old
@@ -74,8 +72,8 @@ timeout: 10s          # per-upstream request timeout
 freshness_ttl: 30s    # freshness-map cache TTL (freshness merge only)
 ```
 
-`backends[*].url` is a **base** URL (`scheme://host[:port]`), without the
-`/pdb/query/v4/...` path — `pdbmux` appends the path per request.
+`backends[*].url` is a **base** URL (`scheme://host[:port]`); `pdbmux` appends
+the `/pdb/query/v4/...` path per request.
 
 | Env var | Overrides |
 |---|---|
@@ -91,66 +89,24 @@ Flags: `--listen`, `--primary`, `--merge`.
 
 ## Running
 
-```bash
-pdbmux                 # start the proxy (serve is the default action)
-pdbmux serve           # explicit
-pdbmux config init     # write a default config file
-pdbmux config show     # print active config after all overrides
-pdbmux version
-```
-
-Point a consumer at it:
+Subcommands: `serve` (default), `config init`, `config show`, `version`. Run
+`pdbmux --help` for details.
 
 ```bash
+PDBMUX_BACKENDS='old=http://puppetdbapi.service.consul:8080,new=https://puppetdb.k8s.syd1.au.unkin.net' pdbmux
 node-lookup --url http://localhost:8080/pdb/query/v4/facts -R
-NODE_LOOKUP_URL=http://localhost:8080/pdb/query/v4/facts pblastreport somehost
 ```
 
 ## Build
 
-```bash
-make build             # -> dist/pdbmux (CGO disabled, static)
-make test              # go test -race ./...
-make lint              # golangci-lint
-```
-
-Requires Go 1.25+. Dependencies: `github.com/spf13/cobra` (CLI),
-`gopkg.in/yaml.v3` (config file).
+`make build` (static binary into `dist/`), `make test`, `make lint`. Requires Go 1.25+.
 
 ## Deployment
 
-`pdbmux` runs **in Kubernetes** as a container, in line with the all-in-k8s
-estate direction — it is not shipped as a per-VM RPM/systemd service. The image
-is built and pushed on every `v*` tag (`.woodpecker/docker.yaml`) to:
+Kubernetes only — no RPM. Every `v*` tag builds and pushes
+`artifactapi.k8s.syd1.au.unkin.net/docker-internal/pdbmux:<tag>`
+(`.woodpecker/docker.yaml`); tag with `make patch` / `minor` / `major`.
 
-```
-artifactapi.k8s.syd1.au.unkin.net/docker-internal/pdbmux:<tag>
-```
-
-It is a minimal static (`CGO_ENABLED=0`) binary on a distroless base
-(`Dockerfile`), configured entirely via `PDBMUX_*` env vars, with a single HTTP
-listener and `/healthz` for liveness/readiness probes.
-
-The Deployment/Service/Gateway manifests live in the estate's `argocd-apps` repo
-under `apps/base/pdbmux/` (namespace `pdbmux`, 2 replicas), and it is exposed to
-VM/workstation `node-lookup` consumers over HTTPS at:
-
-```
-https://pdbmux.k8s.syd1.au.unkin.net
-```
-
-Locally you can still run the binary directly for development:
-
-```bash
-PDBMUX_BACKENDS='old=http://puppetdbapi.service.consul:8080,new=http://puppetdb.puppet.svc.cluster.local:8080' \
-  pdbmux serve
-curl -s localhost:8080/healthz
-```
-
-## Version bumps
-
-```bash
-make patch             # tag vX.Y.(Z+1) and push (triggers the docker release)
-make minor             # tag vX.(Y+1).0
-make major             # tag v(X+1).0.0
-```
+Manifests live in `argocd-apps` under `apps/base/pdbmux/` (namespace `pdbmux`,
+2 replicas). Use `/healthz` for liveness/readiness probes. Reachable from VMs and
+workstations at `https://pdbmux.k8s.syd1.au.unkin.net`.