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

@@ -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

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)
+}

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:

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