Use the go meta-port instead of a hand-rolled go/gofmt symlink

FreeBSD's lang/go is a real meta-port (installs as package name "go")
that depends on whichever goNNN is current and installs the go/gofmt
symlinks itself, tracked and upgradeable - `pkg install go` replaces both
the go125 install and the manual `ln -sf` steps in one command. Verified
against a real base image and rebuild: same resulting symlinks, now
pkg-owned instead of orphaned files pkg doesn't know about.

Docs updated to check for an unversioned meta-port first, falling back to
a manual symlink only when a toolchain doesn't have one.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

1 files changed, 13 insertions, 13 deletions

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
index 00c0f0e..d81ae5d 100644
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -236,9 +236,10 @@ this in a hurry - it's more destructive than "undo."
   is already in FreeBSD base (bmake), so it's never something you need
   to install separately. Watch for versioned port names - FreeBSD's
   `go125`, `python312`, etc. install as that literal binary, not a bare
-  `go`/`python3`; symlink a default into the base image's
-  `/usr/local/bin` if a Makefile invokes the unversioned name. The build
-  step also needs real outbound network access from inside the jail
+  `go`/`python3`. Check for an unversioned meta-port first (`go` itself
+  is one - see [ZFS layout](#1-zfs-layout)); only symlink a default by
+  hand if no meta-port exists for what you need. The build step also
+  needs real outbound network access from inside the jail
   (module/package downloads) - see the `--ip` note under [Provisioning a
   new app](#provisioning-a-new-app).
 - `jail_enable="YES"` in `/etc/rc.conf`:
@@ -277,17 +278,16 @@ wants `/dev/null` and `/dev/random`.) Now install whatever your apps'
 Makefiles actually need to build:
 
 ```
-# pkg -c /skiff/base install -y go125
+# pkg -c /skiff/base install -y go
 ```
 
-Watch for versioned port names - FreeBSD installs `go125` as literally
-`go125`, not `go`, so a Makefile invoking the bare command needs a default
-symlinked in:
-
-```
-# ln -sf go125 /skiff/base/usr/local/bin/go
-# ln -sf gofmt125 /skiff/base/usr/local/bin/gofmt
-```
+FreeBSD's versioned language ports (`go125`, `python312`, ...) install as
+that literal binary name, not a bare `go`/`python3` - a Makefile invoking
+the unversioned command needs one. Check for an unversioned meta-port
+first: `go` is exactly that - it depends on whichever `goNNN` is current
+and installs the `go`/`gofmt` symlinks itself (`pkg install -y go`, not
+`go125` directly, is the whole fix). If no meta-port exists for what you
+need, symlink a default into `/usr/local/bin` by hand instead.
 
 Unmount devfs and snapshot once the image can actually build and run apps:
 
@@ -602,7 +602,7 @@ Carried over from the project's own README, plus what testing surfaced:
 | `git push` says `Everything up-to-date` but you wanted to retry a failed deploy | The git ref already advanced despite the deploy failing - nothing new to push | New commit (`git commit --allow-empty`), or on the host: `skiff deploy --app <app> --new <sha> --ref refs/heads/main` |
 | `build: \`make\` did not produce ./app` | Your Makefile's default target ran (or was skipped as "up to date") without ultimately leaving a file named `app` in the repo root | Run `make -B` locally in a clean checkout and confirm `./app` exists after; check the target actually named `app` (or a dependency of the default target) writes there |
 | Health check fails and you're not sure why | - | `jexec <app> sockstat -4 -l` to check for a listener; `jexec <app> ps aux` to see if the process is even running; try `jexec <app> /app/current/app` directly to see startup errors that daemon(8) would otherwise swallow |
-| Build fails inside the jail with a missing command (`go: not found`, etc.) even though it's installed on the host | The base jail image itself is missing it, or FreeBSD installed it under a versioned name (`go125`, not `go`) | `jexec <app> which <cmd>`; if it's there under a versioned name, symlink a default into the base image's `/usr/local/bin`, re-snapshot, and `skiff rebuild --app <app> --base-snapshot <new-tag>` |
+| Build fails inside the jail with a missing command (`go: not found`, etc.) even though it's installed on the host | The base jail image itself is missing it, or FreeBSD installed it under a versioned name (`go125`, not `go`) | `jexec <app> which <cmd>`; if it's there under a versioned name, check for an unversioned meta-port (`pkg -c /skiff/base install -y go`, not `go125`) before symlinking one by hand; re-snapshot and `skiff rebuild --app <app> --base-snapshot <new-tag>` either way |
 | Build fails inside the jail on any network call (module download, `pkg install`), or `pkg`/`fetch`/`go mod` just time out | The app's `--ip` doesn't actually route from this host - classic jails share the host's routing table, but an out-of-subnet address (e.g. `10.0.0.5` on a host whose real subnet is `192.168.1.0/24`) can send packets that silently never get a response behind some NAT/bridged setups | `jexec <app> fetch -T5 -o /dev/null https://<some-public-ip>` to confirm; if it hangs, re-provision with an `--ip` in the same subnet as the host's own address on `--iface` (see [Provisioning a new app](#provisioning-a-new-app)) |
 | `skiff domains add` fails with a certbot/ACME error | Most likely DNS isn't pointed at the app's `--ip` yet; less commonly, the app's `--ip` doesn't route outbound from this host (see above) | Fix DNS, then re-run `skiff domains add` with the same hostname - safe to retry, the app stays on plain HTTP in the meantime and nothing is left half-configured |