docs(examples): recommend os.UserHomeDir() over hardcoded /tmp/pilot.sock (PILOT-298) - #5

🔍 PR Explanation — #5 PILOT-298

What this does

Adds documentation comments to all five Go examples recommending os.UserHomeDir() / $XDG_RUNTIME_DIR as preferred socket paths over the hardcoded /tmp/pilot.sock.

The problem

All five Go examples hardcode /tmp/pilot.sock as the default daemon socket path:

• On Linux this conflicts with the $XDG_RUNTIME_DIR fallback introduced in PILOT-151
• On macOS this forfeits the SIP per-user /tmp guarantee in edge cases

The fix

Adds a NOTE comment near each flag.String call in all five Go example programs:

• go/client/main.go (+4)
• go/echo/main.go (+4)
• go/httpclient/main.go (+4)
• go/secure/main.go (+4)
• go/webserver/main.go (+4)

The hardcoded /tmp default is preserved for quick-start convenience — this is a documentation-only change.

Verification

• go build ./... — clean
• go vet ./... — clean
• go test ./... — all 5 packages pass
• CI: 4/4 green (go-examples ✅, python-examples ✅, shell-examples ✅, snyk ✅)

Impact

Documentation-only — no behavioral change. Improves developer guidance for cross-platform socket path selection.

🔍 Matthew Explains — #5 PILOT-298

What this does

Adds documentation comments near each flag.String("sock", "/tmp/pilot.sock", ...) call in all five Go examples, recommending os.UserHomeDir() and XDG_RUNTIME_DIR as alternatives to the hardcoded /tmp path.

Why

On Linux, /tmp/pilot.sock conflicts with the XDG_RUNTIME_DIR fallback added in PILOT-151. On macOS, the per-user /tmp guarantee doesn't hold in edge cases under SIP. The examples should steer users toward the portable path.

Changes (5 files, +20 LoC)

• go/client/main.go — add NOTE comment on sock flag
• go/echo/main.go — add NOTE comment on sock flag
• go/httpclient/main.go — add NOTE comment on sock flag
• go/secure/main.go — add NOTE comment on sock flag
• go/webserver/main.go — add NOTE comment on sock flag

The hardcoded /tmp default is preserved for quick-start convenience. This is a documentation-only change (comments only, no code behavior changes).

Canary

Not applicable (docs-only).

📊 Status — PILOT-298

• PR state: Open · Mergeable · No conflicts · No reviews yet
• Canary: Not run — no canary job found for this PR
• Jira: QA/IN-REVIEW — "examples/go: all hardcode /tmp/pilot.sock as socket path" · Assigned: Teodor Calin · Last updated 2026年05月30日
• Operator activity: None — no comments/reviews from @TeoSlayer on this PR yet

🤖 auto-status by matthew-pilot

🤖 PR Status — docs(examples): recommend os.UserHomeDir() over hardcoded /tmp/pilot.sock (PILOT-298)

PR #5 by @matthew-pilot
🔗 #5

Labels

none

CI Checks

• ✅ shell-examples: success
• ✅ python-examples: success
• ✅ go-examples: success

No reviews yet.

Files Changed

5 file(s) changed

• go/client/main.go (+4/-0)
• go/echo/main.go (+4/-0)
• go/httpclient/main.go (+4/-0)
• go/secure/main.go (+4/-0)
• go/webserver/main.go (+4/-0)

_{🤖 automated by matthew-pr-worker | 2026年06月01日T09:10:00Z}

🤖 PR Explanation — docs(examples): recommend os.UserHomeDir() over hardcoded /tmp/pilot.sock (PILOT-298)

What this PR changes

What

All five Go examples (client, echo, httpclient, secure, webserver) hardcode /tmp/pilot.sock as the default daemon socket path. On Linux this conflicts with the XDG_RUNTIME_DIR fallback (PILOT-151 fix) and on macOS forfeits the SIP per-user /tmp guarantee in edge cases.

Fix

Add a NOTE comment near each flag.String call recommending os.UserHomeDir() / XDG_RUNTIME_DIR alternatives. The hardcoded /tmp default is preserved for quick-start convenience — this is a documentation-only change (5 files, +20 LoC).

Verification

$ go build ./... # clean
$ go vet ./... # clean
$ go test ./... # all 5 packages pass

$ git diff --stat HEAD~1
 go/client/main.go | 4 ++++
 go/echo/main.go | 4 ++++
 go/httpclient/main.go | 4 ++++
 go/secure/main.go | 4 ++++
 go/webserver/main.go | 4 ++++
 5 files changed, 20 insertions(+)

Closes PILOT-298

Files Changed

5 file(s) changed

• go/client/main.go (+4/-0)
• go/echo/main.go (+4/-0)
• go/httpclient/main.go (+4/-0)
• go/secure/main.go (+4/-0)
• go/webserver/main.go (+4/-0)

Diff Summary

diff --git a/go/client/main.go b/go/client/main.go
index 1faa2dd..081c6ef 100644
--- a/go/client/main.go
+++ b/go/client/main.go
@@ -13,6 +13,10 @@ import (
 
 func main() {
 	socketPath := flag.String("socket", "/tmp/pilot.sock", "daemon socket path")
+	// NOTE: On Linux, prefer os.UserHomeDir() or XDG_RUNTIME_DIR for the socket
+	// path (e.g. filepath.Join(os.UserHomeDir(), ".pilot", "daemon.sock")).
+	// The hardcoded /tmp default is fine for quick testing but may conflict
+	// with the per-user daemon socket on multi-user systems.
 	target := flag.String("target", "", "target address (e.g. 0:0000.0000.0002:80)")
 	message := flag.String("msg", "hello from pilot client", "message to send")
 	flag.Parse()
diff --git a/go/echo/main.go b/go/echo/main.go
index 531b930..762e27b 100644
--- a/go/echo/main.go
+++ b/go/echo/main.go
@@ -11,6 +11,10 @@ import (
 
 func main() {
 	socketPath := flag.String("socket", "/tmp/pilot.sock", "daemon socket path")
+	// NOTE: On Linux, prefer os.UserHomeDir() or XDG_RUNTIME_DIR for the socket
+	// path (e.g. filepath.Join(os.UserHomeDir(), ".pilot", "daemon.sock")).
+	// The hardcoded /tmp default is fine for quick testing but may conflict
+	// with the per-user daemon socket on multi-user systems.
 	port := flag.Uint("port", 7, "pilot port to listen on")
 	raw := flag.Bool("raw", true, "raw echo (no prefix)")
 	flag.Parse()
diff --git a/go/httpclient/main.go b/go/httpclient/main.go
index 08ae96c..632bce3 100644
--- a/go/httpclient/main.go
++

_{🤖 automated by matthew-pr-worker | 2026年06月01日T09:10:00Z}