From 7c99feb018914e380fe2e376261497adb3c1e956 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= <boschi1997@gmail.com>
Date: Wed, 18 Feb 2026 13:06:17 +0100
Subject: [PATCH] fix(go-client): add go build to CI (#393)

* feat(go-client): add NewAPIClientWithToken helper and expand recall vs reflect FAQ

- Add NewAPIClientWithToken convenience function to Go client for easy authenticated client creation
- Expand FAQ with detailed "When should I use recall vs reflect?" guidance including practical examples

* fix(go-client): add go build to CI and preserve hindsight_client.go in generator

- Add explicit 'go build ./...' step before integration tests for faster compile feedback
- Preserve hindsight_client.go as a maintained file in generate-clients.sh
---
 .github/workflows/test.yml               |  4 ++++
 hindsight-clients/go/hindsight_client.go | 17 ++++++++++++++
 hindsight-docs/src/pages/faq.md          | 30 ++++++++++++++++++++++++
 scripts/generate-clients.sh              |  2 ++
 4 files changed, 53 insertions(+)
 create mode 100644 hindsight-clients/go/hindsight_client.go

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c4bc2421..69c8e34d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -712,6 +712,10 @@ jobs:
           sleep 1
         done
 
+    - name: Build Go client
+      working-directory: ./hindsight-clients/go
+      run: go build ./...
+
     - name: Run Go client tests
       working-directory: ./hindsight-clients/go
       run: go test -v -tags=integration
diff --git a/hindsight-clients/go/hindsight_client.go b/hindsight-clients/go/hindsight_client.go
new file mode 100644
index 00000000..13dc2333
--- /dev/null
+++ b/hindsight-clients/go/hindsight_client.go
@@ -0,0 +1,17 @@
+package hindsight
+
+// NewAPIClientWithToken creates a new API client configured with a base URL and API token.
+// The token is sent as a Bearer token in the Authorization header for all requests.
+//
+// Example:
+//
+//	client := hindsight.NewAPIClientWithToken("https://api.example.com", "your-api-token")
+//	resp, _, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
+func NewAPIClientWithToken(baseURL, token string) *APIClient {
+	cfg := NewConfiguration()
+	cfg.Servers = ServerConfigurations{
+		{URL: baseURL},
+	}
+	cfg.AddDefaultHeader("Authorization", "Bearer "+token)
+	return NewAPIClient(cfg)
+}
diff --git a/hindsight-docs/src/pages/faq.md b/hindsight-docs/src/pages/faq.md
index a0e1e5c7..f448e100 100644
--- a/hindsight-docs/src/pages/faq.md
+++ b/hindsight-docs/src/pages/faq.md
@@ -123,6 +123,36 @@ See [Operations](/developer/api/operations) for API details.
 
 ---
 
+### When should I use recall vs reflect?
+
+**Use recall when:**
+- You want raw facts to feed into your own reasoning or prompt
+- You need maximum control over how memories are interpreted
+- You're doing simple fact lookup (e.g., "What did Alice say about X?")
+- Latency is critical — recall is significantly faster (50-500ms vs 1-10s)
+- You want to build your own answer synthesis layer on top of retrieved memories
+
+**Use reflect when:**
+- You want a ready-to-use answer generated from memories (no extra LLM call needed)
+- You need disposition-aware responses shaped by the bank's personality traits (skepticism, literalism, empathy)
+- The query requires multi-step reasoning across facts, observations, and mental models
+- You need structured output (via `response_schema`) from memory-grounded reasoning
+- You want citations — reflect returns which memories, mental models, and directives informed the answer
+
+**Key difference**: Recall returns data; reflect returns an answer. Recall gives you raw materials, reflect does the reasoning for you using the bank's disposition and an autonomous search loop.
+
+```
+recall("What food does Alice like?")
+→ ["Alice loves sushi", "Alice prefers vegetarian options"]   # raw facts
+
+reflect("What should I order for Alice?")
+→ "I'd recommend a vegetarian sushi platter — Alice loves sushi and prefers vegetarian options."  # grounded answer
+```
+
+See [Recall](/developer/api/recall) and [Reflect](/developer/reflect) for full API details.
+
+---
+
 ### When should I use mental models?
 
 **Mental models** are consolidated knowledge patterns synthesized from individual facts over time. Use them when you need:
diff --git a/scripts/generate-clients.sh b/scripts/generate-clients.sh
index a6f361f2..509eca9f 100755
--- a/scripts/generate-clients.sh
+++ b/scripts/generate-clients.sh
@@ -366,6 +366,7 @@ else
     [ -f "integration_test.go" ] && cp integration_test.go "$TEMP_DIR/"
     [ -f "null_test.go" ] && cp null_test.go "$TEMP_DIR/"
     [ -f "trace_test.go" ] && cp trace_test.go "$TEMP_DIR/"
+    [ -f "hindsight_client.go" ] && cp hindsight_client.go "$TEMP_DIR/"
 
     # Remove old generated files
     echo "Removing old generated code..."
@@ -394,6 +395,7 @@ else
     [ -f "$TEMP_DIR/integration_test.go" ] && mv "$TEMP_DIR/integration_test.go" .
     [ -f "$TEMP_DIR/null_test.go" ] && mv "$TEMP_DIR/null_test.go" .
     [ -f "$TEMP_DIR/trace_test.go" ] && mv "$TEMP_DIR/trace_test.go" .
+    [ -f "$TEMP_DIR/hindsight_client.go" ] && mv "$TEMP_DIR/hindsight_client.go" .
     rm -rf "$TEMP_DIR"
 
     # Fix known generator issue: api_files.go uses os.File but generator omits "os" import