fix(pilotctl,install): stop claiming pilot-gateway ships with the install (#355)

pilot-gateway was extracted to the sibling pilot-protocol/gateway repo
and no longer ships in release tarballs (BINS=daemon/pilotctl/updater
since #186), but several surfaces still told users it was installed:

- pilotctl --help and the machine-readable catalog described it as a
  'separate binary installed alongside pilotctl' — now marked optional
  with a pointer to github.com/pilot-protocol/gateway
- 'pilotctl extras gateway <cmd>' died with a bare internal error when
  the binary was absent — now a not_found error explaining where to
  get it
- install.sh printed the 'Bridge IP traffic' get-started hint
  unconditionally, telling fresh installs to run a command that cannot
  work — now gated on the binary actually existing
- docs/cli-reference.md regenerated

Fresh-install abort itself (cp: pilot-gateway: No such file) was fixed
in the canonical installer (pilot-protocol/release + R2 asset).

Reported by Christopher Powroznik (Bowmark AI) via Slack, 2026-07-06.

Co-authored-by: Teodor Calin <teodor@vulturelabs.io>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

cmd/pilotctl/main.go

@@ -1567,9 +1567,11 @@ Config file: ~/.pilot/config.json
 
 Companion binaries:
   daemon start / start --foreground exec the separately-shipped
-  pilot-daemon binary; gateway start / map exec pilot-gateway. They
-  are discovered (in order): $PILOT_DAEMON_BIN / $PILOT_GATEWAY_BIN,
-  next to the pilotctl executable, then $PATH.
+  pilot-daemon binary; gateway start / map exec pilot-gateway
+  (optional — no longer ships in release tarballs; build it from
+  github.com/pilot-protocol/gateway). Both are discovered (in order):
+  $PILOT_DAEMON_BIN / $PILOT_GATEWAY_BIN, next to the pilotctl
+  executable, then $PATH.
 `)
 	os.Exit(2)
 }
@@ -2095,7 +2097,7 @@ func cmdConfig(args []string) {
 func contextCatalog() map[string]interface{} {
 	return map[string]interface{}{
 		"version": "1.4",
-		"note":    "Core commands cover everything an agent needs. 'app_store' lists the 'pilotctl appstore <sub>' command family (install + call local capability apps). Use 'pilotctl extras <cmd>' for operator/admin operations. 'pilot-gateway' is a separate installed binary.",
+		"note":    "Core commands cover everything an agent needs. 'app_store' lists the 'pilotctl appstore <sub>' command family (install + call local capability apps). Use 'pilotctl extras <cmd>' for operator/admin operations. 'pilot-gateway' is an optional companion binary (not shipped in release tarballs; build from github.com/pilot-protocol/gateway).",
 
 		// ── Core agent commands ──────────────────────────────────────────────
 		"commands": map[string]interface{}{
@@ -2361,7 +2363,7 @@ func contextCatalog() map[string]interface{} {
 		// ── pilot-gateway binary ─────────────────────────────────────────────
 		"pilot_gateway": map[string]interface{}{
 			"binary":      "pilot-gateway",
-			"description": "IP gateway — bridges standard TCP/IP applications to Pilot Protocol addresses. Separate binary installed alongside pilotctl.",
+			"description": "IP gateway — bridges standard TCP/IP applications to Pilot Protocol addresses. Optional companion binary: not shipped in release tarballs, build from github.com/pilot-protocol/gateway.",
 			"commands": map[string]interface{}{
 				"start": map[string]interface{}{
 					"args":        []string{"[--subnet <cidr>]", "[--ports <list>]", "[<pilot-addr>...]"},
@@ -2597,7 +2599,9 @@ func daemonBinaryPath() string {
 func gatewayBinaryPath() string {
 	path, err := findCompanionBinary("pilot-gateway", "PILOT_GATEWAY_BIN")
 	if err != nil {
-		fatalCode("internal", "%v", err)
+		fatalHint("not_found",
+			"pilot-gateway no longer ships in release tarballs — build it from github.com/pilot-protocol/gateway, place it next to pilotctl or on $PATH, or set PILOT_GATEWAY_BIN",
+			"%v", err)
 	}
 	return path
 }

docs/cli-reference.md

@@ -121,7 +121,9 @@ Config file: ~/.pilot/config.json
 
 Companion binaries:
   daemon start / start --foreground exec the separately-shipped
-  pilot-daemon binary; gateway start / map exec pilot-gateway. They
-  are discovered (in order): $PILOT_DAEMON_BIN / $PILOT_GATEWAY_BIN,
-  next to the pilotctl executable, then $PATH.
+  pilot-daemon binary; gateway start / map exec pilot-gateway
+  (optional — no longer ships in release tarballs; build it from
+  github.com/pilot-protocol/gateway). Both are discovered (in order):
+  $PILOT_DAEMON_BIN / $PILOT_GATEWAY_BIN, next to the pilotctl
+  executable, then $PATH.
 ```

install.sh

@@ -708,11 +708,16 @@ echo "  pilotctl daemon start --hostname my-agent    # email already saved"
 echo "  pilotctl info"
 echo "  pilotctl ping <other-agent>"
 echo ""
-echo "Bridge IP traffic (requires root for ports < 1024):"
-echo ""
-echo "  sudo ${BIN_DIR}/pilotctl gateway start --ports 80,3000 <pilot-addr>"
-echo "  curl http://10.4.0.1:3000/status"
-echo ""
+# pilot-gateway no longer ships in release tarballs (extracted to the
+# sibling pilot-protocol/gateway repo) — only show the bridge hint when
+# the binary actually exists on this host.
+if [ -f "$BIN_DIR/pilot-gateway" ]; then
+    echo "Bridge IP traffic (requires root for ports < 1024):"
+    echo ""
+    echo "  sudo ${BIN_DIR}/pilotctl gateway start --ports 80,3000 <pilot-addr>"
+    echo "  curl http://10.4.0.1:3000/status"
+    echo ""
+fi
 echo "Agent skill auto-injection:"
 echo ""
 echo "  The daemon scans every 15 minutes and injects the Pilot Protocol"